@aura3d/core 1.4.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura3d/core",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,6 +11,38 @@
     }
   },
   "dependencies": {
-    "@aura3d/math": "1.4.0"
-  }
+    "@aura3d/math": "1.4.1"
+  },
+  "description": "Engine lifecycle, scheduling, deterministic time stepping, diagnostics, events, logging, task queues, and disposable resource scopes for Aura3D.",
+  "keywords": [
+    "aura3d",
+    "3d",
+    "browser-3d",
+    "web-3d",
+    "typescript",
+    "engine-core",
+    "scheduler",
+    "game-loop",
+    "diagnostics",
+    "events",
+    "lifecycle",
+    "deterministic"
+  ],
+  "homepage": "https://aura3d.auraone.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/auraoneai/aura3d.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/auraoneai/aura3d/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ]
 }

package/src/Diagnostics.ts

@@ -1,80 +0,0 @@
-export type MetricKind = "counter" | "gauge" | "timing";
-
-export interface MetricSnapshot {
-  readonly kind: MetricKind;
-  readonly name: string;
-  readonly value: number;
-  readonly samples: readonly number[];
-}
-
-export interface DiagnosticsSnapshot {
-  readonly metrics: readonly MetricSnapshot[];
-  readonly timestamp: number;
-}
-
-interface MutableMetric {
-  kind: MetricKind;
-  value: number;
-  samples: number[];
-}
-
-export class Diagnostics {
-  private readonly metrics = new Map<string, MutableMetric>();
-  private readonly activeTimers = new Map<string, number>();
-
-  constructor(private readonly maxHistory = 120) {}
-
-  increment(name: string, amount = 1): void {
-    const metric = this.ensure(name, "counter");
-    metric.value += amount;
-    this.recordSample(metric, metric.value);
-  }
-
-  gauge(name: string, value: number): void {
-    const metric = this.ensure(name, "gauge");
-    metric.value = value;
-    this.recordSample(metric, value);
-  }
-
-  begin(name: string): void {
-    if (this.activeTimers.has(name)) throw new Error(`Timer ${name} already started.`);
-    this.activeTimers.set(name, performance.now());
-  }
-
-  end(name: string): number {
-    const start = this.activeTimers.get(name);
-    if (start === undefined) throw new Error(`Timer ${name} was not started.`);
-    this.activeTimers.delete(name);
-    const duration = performance.now() - start;
-    const metric = this.ensure(name, "timing");
-    metric.value = duration;
-    this.recordSample(metric, duration);
-    return duration;
-  }
-
-  snapshot(): DiagnosticsSnapshot {
-    const metrics = [...this.metrics.entries()].map(([name, metric]) => Object.freeze({
-      kind: metric.kind,
-      name,
-      value: metric.value,
-      samples: Object.freeze([...metric.samples])
-    }));
-    return Object.freeze({ metrics: Object.freeze(metrics), timestamp: Date.now() });
-  }
-
-  private ensure(name: string, kind: MetricKind): MutableMetric {
-    const existing = this.metrics.get(name);
-    if (existing) {
-      if (existing.kind !== kind) throw new Error(`Metric ${name} already exists as ${existing.kind}.`);
-      return existing;
-    }
-    const metric: MutableMetric = { kind, value: 0, samples: [] };
-    this.metrics.set(name, metric);
-    return metric;
-  }
-
-  private recordSample(metric: MutableMetric, value: number): void {
-    metric.samples.push(value);
-    if (metric.samples.length > this.maxHistory) metric.samples.shift();
-  }
-}

package/src/Disposable.ts

@@ -1,41 +0,0 @@
-export interface Disposable {
-  dispose(): void | Promise<void>;
-}
-
-export function isDisposable(value: unknown): value is Disposable {
-  return typeof value === "object" && value !== null && "dispose" in value && typeof (value as Disposable).dispose === "function";
-}
-
-export class DisposableStack implements Disposable {
-  private readonly entries: Disposable[] = [];
-  private disposed = false;
-
-  use<T extends Disposable>(resource: T): T {
-    if (this.disposed) {
-      throw new Error("Cannot add a disposable to an already disposed stack.");
-    }
-    this.entries.push(resource);
-    return resource;
-  }
-
-  get size(): number {
-    return this.entries.length;
-  }
-
-  async dispose(): Promise<void> {
-    if (this.disposed) return;
-    this.disposed = true;
-
-    const errors: unknown[] = [];
-    while (this.entries.length > 0) {
-      const entry = this.entries.pop();
-      if (!entry) continue;
-      try {
-        await entry.dispose();
-      } catch (error) {
-        errors.push(error);
-      }
-    }
-    if (errors.length > 0) throw new AggregateError(errors, "One or more disposables failed.");
-  }
-}

package/src/Engine.ts

@@ -1,140 +0,0 @@
-import { DisposableStack } from "./Disposable.js";
-import { EngineLoop, type FrameContext } from "./EngineLoop.js";
-import { resolveEngineConfig, type EngineConfig, type ResolvedEngineConfig } from "./EngineConfig.js";
-import { LifecycleError } from "./Errors.js";
-import { EventBus } from "./EventBus.js";
-import { Diagnostics } from "./Diagnostics.js";
-import { Logger } from "./Logger.js";
-import { ResourceScope } from "./ResourceScope.js";
-import { Scheduler, SystemPhase } from "./Scheduler.js";
-import { TaskQueue } from "./TaskQueue.js";
-
-export type EngineState = "created" | "initializing" | "initialized" | "running" | "stopped" | "disposed" | "failed";
-
-export interface EngineEvents {
-  stateChanged: { readonly previous: EngineState; readonly current: EngineState };
-  frame: FrameContext;
-  error: unknown;
-}
-
-export interface EnginePlugin {
-  readonly id: string;
-  init?(engine: Engine): void | Promise<void>;
-  dispose?(): void | Promise<void>;
-}
-
-export class Engine {
-  readonly config: ResolvedEngineConfig;
-  readonly events = new EventBus<EngineEvents>((error) => this.events.emit("error", error));
-  readonly diagnostics = new Diagnostics();
-  readonly logger = new Logger();
-  readonly scheduler = new Scheduler();
-  readonly tasks = new TaskQueue();
-  readonly resources = new ResourceScope("engine");
-
-  private readonly plugins: EnginePlugin[] = [];
-  private readonly pluginDisposables = new DisposableStack();
-  private readonly loop: EngineLoop;
-  private stateValue: EngineState = "created";
-
-  constructor(config: EngineConfig = {}) {
-    this.config = resolveEngineConfig(config);
-    this.loop = new EngineLoop({
-      mode: "manual",
-      fixedDelta: this.config.fixedDelta,
-      maxDelta: this.config.maxDelta,
-      maxFixedSteps: this.config.maxFixedSteps,
-      timeScale: this.config.timeScale
-    }, (context) => this.runFrame(context));
-  }
-
-  get state(): EngineState {
-    return this.stateValue;
-  }
-
-  use(plugin: EnginePlugin): this {
-    if (this.stateValue !== "created") throw new LifecycleError("PLUGIN_AFTER_INIT", "Plugins must be registered before init.");
-    if (this.plugins.some((existing) => existing.id === plugin.id)) throw new LifecycleError("DUPLICATE_PLUGIN", `Plugin ${plugin.id} already registered.`);
-    this.plugins.push(plugin);
-    return this;
-  }
-
-  async init(): Promise<void> {
-    if (this.stateValue === "initialized" || this.stateValue === "running" || this.stateValue === "stopped") return;
-    if (this.stateValue !== "created") throw new LifecycleError("INVALID_INIT", `Cannot init engine from ${this.stateValue}.`);
-    this.setState("initializing");
-    try {
-      for (const plugin of this.plugins) {
-        await plugin.init?.(this);
-        if (plugin.dispose) this.pluginDisposables.use({ dispose: () => plugin.dispose?.() });
-      }
-      this.setState("initialized");
-      if (this.config.autoStart) this.start();
-    } catch (error) {
-      this.setState("failed");
-      await this.pluginDisposables.dispose();
-      throw error;
-    }
-  }
-
-  start(): void {
-    if (this.stateValue !== "initialized" && this.stateValue !== "stopped") throw new LifecycleError("START_BEFORE_INIT", "Engine must be initialized before start.");
-    this.loop.start();
-    this.setState("running");
-  }
-
-  stop(): void {
-    if (this.stateValue !== "running") return;
-    this.loop.stop();
-    this.setState("stopped");
-  }
-
-  async step(delta: number): Promise<FrameContext> {
-    if (this.stateValue === "created") await this.init();
-    if (this.stateValue !== "initialized" && this.stateValue !== "running" && this.stateValue !== "stopped") {
-      throw new LifecycleError("STEP_INVALID_STATE", `Cannot step engine from ${this.stateValue}.`);
-    }
-    return this.loop.step(delta);
-  }
-
-  async dispose(): Promise<void> {
-    if (this.stateValue === "disposed") return;
-    if (this.stateValue === "running") this.stop();
-    const errors: unknown[] = [];
-    try {
-      await this.pluginDisposables.dispose();
-    } catch (error) {
-      errors.push(error);
-    }
-    try {
-      await this.resources.dispose();
-    } catch (error) {
-      errors.push(error);
-    }
-    this.events.clear();
-    this.setState("disposed");
-    if (errors.length > 0) throw new AggregateError(errors, "Engine disposal failed.");
-  }
-
-  private async runFrame(context: FrameContext): Promise<void> {
-    this.diagnostics.increment("frames");
-    await this.scheduler.runPhase(SystemPhase.Platform);
-    await this.scheduler.runPhase(SystemPhase.Tasks);
-    await this.tasks.flush();
-    for (let step = 0; step < context.fixedSteps; step++) {
-      await this.scheduler.runPhase(SystemPhase.Fixed, step);
-    }
-    await this.scheduler.runPhase(SystemPhase.Update);
-    await this.scheduler.runPhase(SystemPhase.Scene);
-    await this.scheduler.runPhase(SystemPhase.Render);
-    await this.scheduler.runPhase(SystemPhase.Present);
-    await this.scheduler.runPhase(SystemPhase.Cleanup);
-    this.events.emit("frame", context);
-  }
-
-  private setState(next: EngineState): void {
-    const previous = this.stateValue;
-    this.stateValue = next;
-    this.events.emit("stateChanged", Object.freeze({ previous, current: next }));
-  }
-}

package/src/EngineConfig.ts

@@ -1,38 +0,0 @@
-import { ValidationError } from "./Errors.js";
-
-export interface EngineConfig {
-  targetFPS?: number;
-  fixedDelta?: number;
-  maxDelta?: number;
-  maxFixedSteps?: number;
-  timeScale?: number;
-  autoStart?: boolean;
-}
-
-export interface ResolvedEngineConfig {
-  readonly targetFPS: number;
-  readonly fixedDelta: number;
-  readonly maxDelta: number;
-  readonly maxFixedSteps: number;
-  readonly timeScale: number;
-  readonly autoStart: boolean;
-}
-
-export function resolveEngineConfig(config: EngineConfig = {}): ResolvedEngineConfig {
-  const resolved = {
-    targetFPS: config.targetFPS ?? 60,
-    fixedDelta: config.fixedDelta ?? 1 / 60,
-    maxDelta: config.maxDelta ?? 0.25,
-    maxFixedSteps: config.maxFixedSteps ?? 5,
-    timeScale: config.timeScale ?? 1,
-    autoStart: config.autoStart ?? false
-  };
-
-  if (!Number.isFinite(resolved.targetFPS) || resolved.targetFPS <= 0) throw new ValidationError("INVALID_TARGET_FPS", "targetFPS must be positive.");
-  if (!Number.isFinite(resolved.fixedDelta) || resolved.fixedDelta <= 0) throw new ValidationError("INVALID_FIXED_DELTA", "fixedDelta must be positive.");
-  if (!Number.isFinite(resolved.maxDelta) || resolved.maxDelta <= 0) throw new ValidationError("INVALID_MAX_DELTA", "maxDelta must be positive.");
-  if (!Number.isInteger(resolved.maxFixedSteps) || resolved.maxFixedSteps <= 0) throw new ValidationError("INVALID_MAX_FIXED_STEPS", "maxFixedSteps must be a positive integer.");
-  if (!Number.isFinite(resolved.timeScale) || resolved.timeScale < 0) throw new ValidationError("INVALID_TIME_SCALE", "timeScale must be finite and non-negative.");
-
-  return Object.freeze(resolved);
-}

package/src/EngineLoop.ts

@@ -1,83 +0,0 @@
-import { FixedStepAccumulator } from "./FixedStepAccumulator.js";
-import { Time, type TimeSnapshot } from "./Time.js";
-
-export type LoopMode = "manual" | "raf";
-
-export interface FrameContext {
-  readonly time: TimeSnapshot;
-  readonly fixedSteps: number;
-  readonly interpolationAlpha: number;
-}
-
-export type FrameCallback = (context: FrameContext) => void | Promise<void>;
-
-export interface EngineLoopOptions {
-  readonly mode: LoopMode;
-  readonly fixedDelta: number;
-  readonly maxDelta: number;
-  readonly maxFixedSteps: number;
-  readonly timeScale?: number;
-}
-
-export class EngineLoop {
-  private readonly time: Time;
-  private readonly accumulator: FixedStepAccumulator;
-  private running = false;
-  private rafHandle: number | undefined;
-  private lastTimestamp: number | undefined;
-
-  constructor(
-    private readonly options: EngineLoopOptions,
-    private readonly onFrame: FrameCallback
-  ) {
-    this.time = new Time(options.maxDelta, options.timeScale ?? 1);
-    this.accumulator = new FixedStepAccumulator(options.fixedDelta, options.maxFixedSteps);
-  }
-
-  start(): void {
-    if (this.running) return;
-    this.running = true;
-    if (this.options.mode === "raf") {
-      if (typeof requestAnimationFrame !== "function") throw new Error("requestAnimationFrame is unavailable.");
-      this.lastTimestamp = undefined;
-      this.rafHandle = requestAnimationFrame((timestamp) => void this.tickRaf(timestamp));
-    }
-  }
-
-  stop(): void {
-    if (!this.running) return;
-    this.running = false;
-    if (this.rafHandle !== undefined && typeof cancelAnimationFrame === "function") {
-      cancelAnimationFrame(this.rafHandle);
-    }
-    this.rafHandle = undefined;
-  }
-
-  pause(): void {
-    this.stop();
-  }
-
-  resume(): void {
-    this.start();
-  }
-
-  async step(delta: number): Promise<FrameContext> {
-    const time = this.time.update(delta);
-    const fixed = this.accumulator.add(time.delta);
-    const context = Object.freeze({ time, fixedSteps: fixed.steps, interpolationAlpha: fixed.alpha });
-    await this.onFrame(context);
-    return context;
-  }
-
-  snapshot(): TimeSnapshot {
-    return this.time.snapshot();
-  }
-
-  private async tickRaf(timestamp: number): Promise<void> {
-    if (!this.running) return;
-    const delta = this.lastTimestamp === undefined ? 0 : (timestamp - this.lastTimestamp) / 1000;
-    this.lastTimestamp = timestamp;
-    await this.step(delta);
-    if (this.running) this.rafHandle = requestAnimationFrame((nextTimestamp) => void this.tickRaf(nextTimestamp));
-  }
-}

package/src/Errors.ts

@@ -1,28 +0,0 @@
-export class EngineError extends Error {
-  constructor(
-    readonly code: string,
-    message: string,
-    options?: ErrorOptions
-  ) {
-    super(message, options);
-    this.name = new.target.name;
-  }
-}
-
-export class LifecycleError extends EngineError {
-  constructor(code: string, message: string, options?: ErrorOptions) {
-    super(`LIFECYCLE_${code}`, message, options);
-  }
-}
-
-export class ValidationError extends EngineError {
-  constructor(code: string, message: string, options?: ErrorOptions) {
-    super(`VALIDATION_${code}`, message, options);
-  }
-}
-
-export class ResourceError extends EngineError {
-  constructor(code: string, message: string, options?: ErrorOptions) {
-    super(`RESOURCE_${code}`, message, options);
-  }
-}

package/src/EventBus.ts

@@ -1,52 +0,0 @@
-export type EventMapBase = object;
-export type EventListener<T> = (event: T) => void;
-export type EventErrorHandler = (error: unknown, eventName: string) => void;
-
-export interface Subscription {
-  unsubscribe(): void;
-}
-
-export class EventBus<TEvents extends EventMapBase> {
-  private readonly listeners = new Map<keyof TEvents, Set<EventListener<TEvents[keyof TEvents]>>>();
-  private readonly onceListeners = new WeakSet<EventListener<TEvents[keyof TEvents]>>();
-
-  constructor(private readonly onListenerError?: EventErrorHandler) {}
-
-  on<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): Subscription {
-    const set = this.listeners.get(eventName) ?? new Set<EventListener<TEvents[keyof TEvents]>>();
-    set.add(listener as EventListener<TEvents[keyof TEvents]>);
-    this.listeners.set(eventName, set);
-    return { unsubscribe: () => this.off(eventName, listener) };
-  }
-
-  once<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): Subscription {
-    const subscription = this.on(eventName, listener);
-    this.onceListeners.add(listener as EventListener<TEvents[keyof TEvents]>);
-    return subscription;
-  }
-
-  off<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): void {
-    const set = this.listeners.get(eventName);
-    set?.delete(listener as EventListener<TEvents[keyof TEvents]>);
-    if (set?.size === 0) this.listeners.delete(eventName);
-  }
-
-  emit<K extends keyof TEvents>(eventName: K, event: TEvents[K]): void {
-    const snapshot = [...(this.listeners.get(eventName) ?? [])];
-    for (const listener of snapshot) {
-      if (!this.listeners.get(eventName)?.has(listener)) continue;
-      try {
-        (listener as EventListener<TEvents[K]>)(event);
-      } catch (error) {
-        this.onListenerError?.(error, String(eventName));
-      }
-      if (this.onceListeners.has(listener)) {
-        this.listeners.get(eventName)?.delete(listener);
-      }
-    }
-  }
-
-  clear(): void {
-    this.listeners.clear();
-  }
-}

package/src/FixedStepAccumulator.ts

@@ -1,39 +0,0 @@
-export interface FixedStepResult {
-  readonly steps: number;
-  readonly alpha: number;
-  readonly droppedTime: number;
-}
-
-export class FixedStepAccumulator {
-  private accumulator = 0;
-
-  constructor(
-    readonly fixedDelta: number,
-    readonly maxSteps: number
-  ) {
-    if (!Number.isFinite(fixedDelta) || fixedDelta <= 0) throw new RangeError("fixedDelta must be finite and positive.");
-    if (!Number.isInteger(maxSteps) || maxSteps <= 0) throw new RangeError("maxSteps must be a positive integer.");
-  }
-
-  add(delta: number): FixedStepResult {
-    if (!Number.isFinite(delta) || delta < 0) throw new RangeError("delta must be finite and non-negative.");
-    this.accumulator += delta;
-    const possibleSteps = Math.floor(this.accumulator / this.fixedDelta);
-    const steps = Math.min(possibleSteps, this.maxSteps);
-    this.accumulator -= steps * this.fixedDelta;
-    let droppedTime = 0;
-    if (possibleSteps > this.maxSteps) {
-      droppedTime = this.accumulator;
-      this.accumulator = 0;
-    }
-    return Object.freeze({ steps, alpha: this.alpha, droppedTime });
-  }
-
-  get alpha(): number {
-    return this.accumulator / this.fixedDelta;
-  }
-
-  reset(): void {
-    this.accumulator = 0;
-  }
-}

package/src/Logger.ts

@@ -1,67 +0,0 @@
-export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
-
-export interface LogEntry {
-  readonly level: Exclude<LogLevel, "silent">;
-  readonly category: string;
-  readonly message: string;
-  readonly timestamp: number;
-  readonly data?: unknown;
-}
-
-export type LogSink = (entry: LogEntry) => void;
-
-const levelRank: Record<LogLevel, number> = {
-  debug: 10,
-  info: 20,
-  warn: 30,
-  error: 40,
-  silent: 50
-};
-
-export class Logger {
-  private readonly sinks = new Set<LogSink>();
-  private readonly lastEmitted = new Map<string, number>();
-
-  constructor(private level: LogLevel = "info") {}
-
-  setLevel(level: LogLevel): void {
-    this.level = level;
-  }
-
-  addSink(sink: LogSink): () => void {
-    this.sinks.add(sink);
-    return () => this.sinks.delete(sink);
-  }
-
-  debug(category: string, message: string, data?: unknown): void {
-    this.log("debug", category, message, data);
-  }
-
-  info(category: string, message: string, data?: unknown): void {
-    this.log("info", category, message, data);
-  }
-
-  warn(category: string, message: string, data?: unknown): void {
-    this.log("warn", category, message, data);
-  }
-
-  error(category: string, message: string, data?: unknown): void {
-    this.log("error", category, message, data);
-  }
-
-  log(level: Exclude<LogLevel, "silent">, category: string, message: string, data?: unknown, rateLimitMs = 0): void {
-    if (levelRank[level] < levelRank[this.level]) return;
-    const key = `${level}:${category}:${message}`;
-    const now = Date.now();
-    if (rateLimitMs > 0 && now - (this.lastEmitted.get(key) ?? -Infinity) < rateLimitMs) return;
-    this.lastEmitted.set(key, now);
-    const entry: LogEntry = Object.freeze({ level, category, message, timestamp: now, data });
-    for (const sink of [...this.sinks]) {
-      try {
-        sink(entry);
-      } catch {
-        this.sinks.delete(sink);
-      }
-    }
-  }
-}

package/src/ResourceScope.ts

@@ -1,55 +0,0 @@
-import { DisposableStack, type Disposable } from "./Disposable.js";
-
-export interface ResourceLeak {
-  name: string;
-  resourceCount: number;
-  childScopes: ResourceLeak[];
-}
-
-export class ResourceScope implements Disposable {
-  private readonly stack = new DisposableStack();
-  private readonly children = new Set<ResourceScope>();
-  private disposed = false;
-
-  constructor(readonly name: string) {}
-
-  use<T extends Disposable>(resource: T): T {
-    if (this.disposed) throw new Error(`Resource scope ${this.name} is disposed.`);
-    return this.stack.use(resource);
-  }
-
-  createChild(name: string): ResourceScope {
-    if (this.disposed) throw new Error(`Resource scope ${this.name} is disposed.`);
-    const child = new ResourceScope(name);
-    this.children.add(child);
-    return child;
-  }
-
-  leakSnapshot(): ResourceLeak {
-    return {
-      name: this.name,
-      resourceCount: this.stack.size,
-      childScopes: [...this.children].map((child) => child.leakSnapshot())
-    };
-  }
-
-  async dispose(): Promise<void> {
-    if (this.disposed) return;
-    this.disposed = true;
-    const errors: unknown[] = [];
-    for (const child of [...this.children].reverse()) {
-      try {
-        await child.dispose();
-      } catch (error) {
-        errors.push(error);
-      }
-    }
-    this.children.clear();
-    try {
-      await this.stack.dispose();
-    } catch (error) {
-      errors.push(error);
-    }
-    if (errors.length > 0) throw new AggregateError(errors, `Resource scope ${this.name} failed to dispose.`);
-  }
-}

package/src/Scheduler.ts

@@ -1,94 +0,0 @@
-import { ValidationError } from "./Errors.js";
-
-export const SystemPhase = Object.freeze({
-  Platform: "platform",
-  Tasks: "tasks",
-  Fixed: "fixed",
-  Update: "update",
-  Scene: "scene",
-  Render: "render",
-  Present: "present",
-  Cleanup: "cleanup"
-});
-
-export type SystemPhase = (typeof SystemPhase)[keyof typeof SystemPhase];
-
-export interface SchedulerContext {
-  readonly phase: SystemPhase;
-  readonly fixedStepIndex?: number;
-}
-
-export interface ScheduledTask {
-  readonly id: string;
-  readonly phase: SystemPhase;
-  readonly dependsOn?: readonly string[];
-  readonly enabled?: boolean;
-  run(context: SchedulerContext): void | Promise<void>;
-}
-
-const phaseOrder = Object.values(SystemPhase);
-
-export class Scheduler {
-  private readonly tasks = new Map<string, ScheduledTask>();
-
-  add(task: ScheduledTask): void {
-    if (this.tasks.has(task.id)) throw new ValidationError("DUPLICATE_TASK", `Task ${task.id} already exists.`);
-    this.tasks.set(task.id, task);
-  }
-
-  remove(id: string): void {
-    this.tasks.delete(id);
-  }
-
-  getExecutionPlan(): readonly ScheduledTask[] {
-    const ordered: ScheduledTask[] = [];
-    const byPhase = new Map<SystemPhase, ScheduledTask[]>();
-    for (const task of this.tasks.values()) {
-      if (task.enabled === false) continue;
-      const list = byPhase.get(task.phase) ?? [];
-      list.push(task);
-      byPhase.set(task.phase, list);
-    }
-
-    for (const phase of phaseOrder) {
-      ordered.push(...this.sortPhase(byPhase.get(phase) ?? []));
-    }
-    return Object.freeze(ordered);
-  }
-
-  async runPhase(phase: SystemPhase, fixedStepIndex?: number): Promise<void> {
-    for (const task of this.getExecutionPlan()) {
-      if (task.phase === phase) {
-        const context: SchedulerContext = fixedStepIndex === undefined ? { phase } : { phase, fixedStepIndex };
-        await task.run(context);
-      }
-    }
-  }
-
-  private sortPhase(tasks: readonly ScheduledTask[]): ScheduledTask[] {
-    const taskIds = new Set(tasks.map((task) => task.id));
-    const visiting = new Set<string>();
-    const visited = new Set<string>();
-    const output: ScheduledTask[] = [];
-    const taskById = new Map(tasks.map((task) => [task.id, task]));
-
-    const visit = (task: ScheduledTask): void => {
-      if (visited.has(task.id)) return;
-      if (visiting.has(task.id)) throw new ValidationError("TASK_CYCLE", `Scheduler cycle includes ${task.id}.`);
-      visiting.add(task.id);
-      for (const dependency of task.dependsOn ?? []) {
-        const dep = this.tasks.get(dependency);
-        if (!dep || dep.enabled === false) throw new ValidationError("MISSING_DEPENDENCY", `Task ${task.id} depends on missing task ${dependency}.`);
-        if (dep.phase !== task.phase) throw new ValidationError("CROSS_PHASE_DEPENDENCY", `Task ${task.id} depends on ${dependency} in a different phase.`);
-        if (!taskIds.has(dependency)) throw new ValidationError("MISSING_DEPENDENCY", `Task ${task.id} depends on missing phase peer ${dependency}.`);
-        visit(taskById.get(dependency)!);
-      }
-      visiting.delete(task.id);
-      visited.add(task.id);
-      output.push(task);
-    };
-
-    for (const task of tasks) visit(task);
-    return output;
-  }
-}

package/src/TaskQueue.ts

@@ -1,50 +0,0 @@
-export interface TaskHandle {
-  readonly id: number;
-  cancel(): void;
-  readonly cancelled: boolean;
-}
-
-interface QueuedTask {
-  handle: MutableTaskHandle;
-  task: () => void | Promise<void>;
-}
-
-class MutableTaskHandle implements TaskHandle {
-  cancelled = false;
-  constructor(readonly id: number) {}
-  cancel(): void {
-    this.cancelled = true;
-  }
-}
-
-export class TaskQueue {
-  private queue: QueuedTask[] = [];
-  private nextId = 1;
-
-  enqueue(task: () => void | Promise<void>): TaskHandle {
-    const handle = new MutableTaskHandle(this.nextId++);
-    this.queue.push({ handle, task });
-    return handle;
-  }
-
-  get size(): number {
-    return this.queue.length;
-  }
-
-  async flush(): Promise<void> {
-    const errors: unknown[] = [];
-    while (this.queue.length > 0) {
-      const batch = this.queue;
-      this.queue = [];
-      for (const item of batch) {
-        if (item.handle.cancelled) continue;
-        try {
-          await item.task();
-        } catch (error) {
-          errors.push(error);
-        }
-      }
-    }
-    if (errors.length > 0) throw new AggregateError(errors, "One or more queued tasks failed.");
-  }
-}

package/src/Time.ts

@@ -1,54 +0,0 @@
-export interface TimeSnapshot {
-  readonly frame: number;
-  readonly elapsed: number;
-  readonly unscaledElapsed: number;
-  readonly delta: number;
-  readonly unscaledDelta: number;
-  readonly smoothedDelta: number;
-  readonly timeScale: number;
-}
-
-export class Time {
-  private frameValue = 0;
-  private elapsedValue = 0;
-  private unscaledElapsedValue = 0;
-  private deltaValue = 0;
-  private unscaledDeltaValue = 0;
-  private smoothedDeltaValue = 0;
-
-  constructor(
-    private readonly maxDelta: number,
-    private timeScaleValue = 1
-  ) {
-    if (!Number.isFinite(maxDelta) || maxDelta <= 0) throw new RangeError("maxDelta must be finite and positive.");
-    this.setTimeScale(timeScaleValue);
-  }
-
-  setTimeScale(timeScale: number): void {
-    if (!Number.isFinite(timeScale) || timeScale < 0) throw new RangeError("timeScale must be finite and non-negative.");
-    this.timeScaleValue = timeScale;
-  }
-
-  update(unscaledDelta: number): TimeSnapshot {
-    if (!Number.isFinite(unscaledDelta) || unscaledDelta < 0) throw new RangeError("delta must be finite and non-negative.");
-    this.unscaledDeltaValue = Math.min(unscaledDelta, this.maxDelta);
-    this.deltaValue = this.unscaledDeltaValue * this.timeScaleValue;
-    this.unscaledElapsedValue += this.unscaledDeltaValue;
-    this.elapsedValue += this.deltaValue;
-    this.frameValue++;
-    this.smoothedDeltaValue = this.frameValue === 1 ? this.deltaValue : this.smoothedDeltaValue * 0.9 + this.deltaValue * 0.1;
-    return this.snapshot();
-  }
-
-  snapshot(): TimeSnapshot {
-    return Object.freeze({
-      frame: this.frameValue,
-      elapsed: this.elapsedValue,
-      unscaledElapsed: this.unscaledElapsedValue,
-      delta: this.deltaValue,
-      unscaledDelta: this.unscaledDeltaValue,
-      smoothedDelta: this.smoothedDeltaValue,
-      timeScale: this.timeScaleValue
-    });
-  }
-}

package/src/VersionedSerialization.ts

@@ -1,351 +0,0 @@
-import { ValidationError } from "./Errors.js";
-
-export type VersionedFieldKind =
-  | "boolean"
-  | "int32"
-  | "uint32"
-  | "float32"
-  | "float64"
-  | "string"
-  | "array"
-  | "object";
-
-export interface VersionedSchemaField {
-  readonly name: string;
-  readonly kind: VersionedFieldKind;
-  readonly required?: boolean;
-  readonly defaultValue?: unknown;
-  readonly elementKind?: VersionedFieldKind;
-  readonly schema?: VersionedSchema;
-}
-
-export interface VersionedSchemaValidation {
-  readonly ok: boolean;
-  readonly issues: readonly string[];
-}
-
-export class VersionedSchema {
-  private readonly fields = new Map<string, VersionedSchemaField>();
-
-  constructor(readonly name: string, readonly version: number) {
-    if (!name.trim()) throw new ValidationError("SCHEMA_NAME", "VersionedSchema requires a non-empty name.");
-    if (!Number.isSafeInteger(version) || version < 0) throw new ValidationError("SCHEMA_VERSION", "VersionedSchema version must be a non-negative integer.");
-  }
-
-  addField(field: VersionedSchemaField): this {
-    if (!field.name.trim()) throw new ValidationError("SCHEMA_FIELD", "Schema field requires a non-empty name.");
-    if (this.fields.has(field.name)) throw new ValidationError("SCHEMA_FIELD_DUPLICATE", `Duplicate schema field: ${field.name}`);
-    if (field.kind === "array" && !field.elementKind) throw new ValidationError("SCHEMA_ARRAY_ELEMENT", `Array field ${field.name} requires elementKind.`);
-    this.fields.set(field.name, field);
-    return this;
-  }
-
-  getField(name: string): VersionedSchemaField | undefined {
-    return this.fields.get(name);
-  }
-
-  getFields(): readonly VersionedSchemaField[] {
-    return [...this.fields.values()];
-  }
-
-  validate(data: unknown): VersionedSchemaValidation {
-    const issues: string[] = [];
-    if (!isRecord(data)) {
-      return { ok: false, issues: [`${this.name} must be an object.`] };
-    }
-    for (const field of this.fields.values()) {
-      const value = data[field.name];
-      if (value === undefined) {
-        if (field.required && field.defaultValue === undefined) issues.push(`${field.name} is required.`);
-        continue;
-      }
-      collectTypeIssues(value, field, field.name, issues);
-    }
-    return { ok: issues.length === 0, issues };
-  }
-
-  serialize(data: unknown): Record<string, unknown> {
-    const validation = this.validate(data);
-    if (!validation.ok) throw new ValidationError("SCHEMA_VALIDATE", validation.issues.join(" "));
-    const record = data as Record<string, unknown>;
-    const result: Record<string, unknown> = {};
-    for (const field of this.fields.values()) {
-      const value = record[field.name];
-      if (value !== undefined) {
-        result[field.name] = value;
-      } else if (field.defaultValue !== undefined) {
-        result[field.name] = cloneValue(field.defaultValue);
-      }
-    }
-    return result;
-  }
-
-  deserialize(data: unknown): Record<string, unknown> {
-    return this.serialize(data);
-  }
-
-  static builder(name: string, version: number): VersionedSchemaBuilder {
-    return new VersionedSchemaBuilder(name, version);
-  }
-}
-
-export class VersionedSchemaBuilder {
-  private readonly schema: VersionedSchema;
-
-  constructor(name: string, version: number) {
-    this.schema = new VersionedSchema(name, version);
-  }
-
-  boolean(name: string, options: FieldOptions<boolean> = {}): this {
-    return this.field({ name, kind: "boolean", ...options });
-  }
-
-  int32(name: string, options: FieldOptions<number> = {}): this {
-    return this.field({ name, kind: "int32", ...options });
-  }
-
-  uint32(name: string, options: FieldOptions<number> = {}): this {
-    return this.field({ name, kind: "uint32", ...options });
-  }
-
-  float32(name: string, options: FieldOptions<number> = {}): this {
-    return this.field({ name, kind: "float32", ...options });
-  }
-
-  string(name: string, options: FieldOptions<string> = {}): this {
-    return this.field({ name, kind: "string", ...options });
-  }
-
-  array(name: string, elementKind: VersionedFieldKind, options: FieldOptions<readonly unknown[]> = {}): this {
-    return this.field({ name, kind: "array", elementKind, ...options });
-  }
-
-  object(name: string, schema?: VersionedSchema, options: FieldOptions<Record<string, unknown>> = {}): this {
-    return this.field({ name, kind: "object", schema, ...options });
-  }
-
-  field(field: VersionedSchemaField): this {
-    this.schema.addField(field);
-    return this;
-  }
-
-  build(): VersionedSchema {
-    return this.schema;
-  }
-}
-
-export interface FieldOptions<T> {
-  readonly required?: boolean;
-  readonly defaultValue?: T;
-}
-
-export interface MigrationDefinition<T = unknown> {
-  readonly from: number;
-  readonly to: number;
-  readonly description?: string;
-  migrate(data: T): T;
-}
-
-export class MigrationRegistry<T = unknown> {
-  private readonly migrations = new Map<number, MigrationDefinition<T>[]>();
-
-  register(migration: MigrationDefinition<T>): this {
-    if (!Number.isSafeInteger(migration.from) || !Number.isSafeInteger(migration.to) || migration.to <= migration.from) {
-      throw new ValidationError("MIGRATION_VERSION", "Migration must move from a lower integer version to a higher integer version.");
-    }
-    const list = this.migrations.get(migration.from) ?? [];
-    if (list.some((entry) => entry.to === migration.to)) {
-      throw new ValidationError("MIGRATION_DUPLICATE", `Duplicate migration path: ${migration.from} -> ${migration.to}`);
-    }
-    list.push(migration);
-    list.sort((left, right) => left.to - right.to);
-    this.migrations.set(migration.from, list);
-    return this;
-  }
-
-  canMigrate(from: number, to: number): boolean {
-    try {
-      this.plan(from, to);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  migrate(data: T, from: number, to: number): T {
-    let current = data;
-    for (const migration of this.plan(from, to)) {
-      current = migration.migrate(current);
-    }
-    return current;
-  }
-
-  list(): readonly MigrationDefinition<T>[] {
-    return [...this.migrations.values()].flat().sort((left, right) => left.from - right.from || left.to - right.to);
-  }
-
-  private plan(from: number, to: number): readonly MigrationDefinition<T>[] {
-    if (from === to) return [];
-    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from > to) {
-      throw new ValidationError("MIGRATION_TARGET", "Migration target must be an integer version greater than or equal to the source.");
-    }
-    const plan: MigrationDefinition<T>[] = [];
-    let current = from;
-    while (current < to) {
-      const next = (this.migrations.get(current) ?? []).find((migration) => migration.to <= to);
-      if (!next) throw new ValidationError("MIGRATION_PATH", `No migration path from version ${current} to ${to}.`);
-      plan.push(next);
-      current = next.to;
-    }
-    return plan;
-  }
-}
-
-export type SaveSlotFormat = "json" | "binary";
-
-export interface SaveSlotMetadata {
-  readonly name?: string;
-  readonly description?: string;
-  readonly playTime?: number;
-  readonly version?: string;
-  readonly autoSave?: boolean;
-  readonly [key: string]: unknown;
-}
-
-export interface SerializedSaveSlot {
-  readonly id: string;
-  readonly format: SaveSlotFormat;
-  readonly timestamp: number;
-  readonly metadata: SaveSlotMetadata;
-  readonly compressed: boolean;
-  readonly data: string;
-}
-
-export class SaveSlot {
-  private data: string | Uint8Array | null = null;
-  private format: SaveSlotFormat = "json";
-  private timestamp: number;
-  private metadata: SaveSlotMetadata = {};
-  private compressed = false;
-
-  constructor(readonly id: string, timestamp = Date.now()) {
-    if (!id.trim()) throw new ValidationError("SAVE_SLOT_ID", "SaveSlot requires a non-empty id.");
-    this.timestamp = timestamp;
-  }
-
-  setData(data: string | Uint8Array, format: SaveSlotFormat, options: { readonly compressed?: boolean } = {}): void {
-    this.data = typeof data === "string" ? data : new Uint8Array(data);
-    this.format = format;
-    this.compressed = options.compressed ?? false;
-    this.timestamp = Date.now();
-  }
-
-  getData(): string | Uint8Array | null {
-    return typeof this.data === "string" || this.data === null ? this.data : new Uint8Array(this.data);
-  }
-
-  getFormat(): SaveSlotFormat {
-    return this.format;
-  }
-
-  getTimestamp(): number {
-    return this.timestamp;
-  }
-
-  getMetadata(): SaveSlotMetadata {
-    return { ...this.metadata };
-  }
-
-  setMetadata(metadata: SaveSlotMetadata): void {
-    this.metadata = { ...this.metadata, ...metadata };
-  }
-
-  isCompressed(): boolean {
-    return this.compressed;
-  }
-
-  getSize(): number {
-    if (this.data === null) return 0;
-    return typeof this.data === "string" ? new TextEncoder().encode(this.data).byteLength : this.data.byteLength;
-  }
-
-  toJSON(): SerializedSaveSlot {
-    return {
-      id: this.id,
-      format: this.format,
-      timestamp: this.timestamp,
-      metadata: { ...this.metadata },
-      compressed: this.compressed,
-      data: this.data instanceof Uint8Array ? bytesToBase64(this.data) : this.data ?? ""
-    };
-  }
-
-  static fromJSON(serialized: SerializedSaveSlot): SaveSlot {
-    const slot = new SaveSlot(serialized.id, serialized.timestamp);
-    slot.format = serialized.format;
-    slot.metadata = { ...serialized.metadata };
-    slot.compressed = serialized.compressed;
-    slot.data = serialized.format === "binary" ? base64ToBytes(serialized.data) : serialized.data;
-    return slot;
-  }
-}
-
-function collectTypeIssues(value: unknown, field: VersionedSchemaField, path: string, issues: string[]): void {
-  if (!matchesKind(value, field.kind)) {
-    issues.push(`${path} expected ${field.kind}.`);
-    return;
-  }
-  if (field.kind === "array" && field.elementKind && Array.isArray(value)) {
-    value.forEach((entry, index) => {
-      if (!matchesKind(entry, field.elementKind as VersionedFieldKind)) issues.push(`${path}[${index}] expected ${field.elementKind}.`);
-    });
-  }
-  if (field.kind === "object" && field.schema) {
-    const nested = field.schema.validate(value);
-    for (const issue of nested.issues) issues.push(`${path}.${issue}`);
-  }
-}
-
-function matchesKind(value: unknown, kind: VersionedFieldKind): boolean {
-  switch (kind) {
-    case "boolean":
-      return typeof value === "boolean";
-    case "int32":
-      return Number.isInteger(value) && Number(value) >= -2147483648 && Number(value) <= 2147483647;
-    case "uint32":
-      return Number.isInteger(value) && Number(value) >= 0 && Number(value) <= 4294967295;
-    case "float32":
-    case "float64":
-      return typeof value === "number" && Number.isFinite(value);
-    case "string":
-      return typeof value === "string";
-    case "array":
-      return Array.isArray(value);
-    case "object":
-      return isRecord(value);
-  }
-}
-
-function cloneValue(value: unknown): unknown {
-  if (typeof structuredClone === "function") return structuredClone(value);
-  return JSON.parse(JSON.stringify(value)) as unknown;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function bytesToBase64(bytes: Uint8Array): string {
-  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary);
-}
-
-function base64ToBytes(base64: string): Uint8Array {
-  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(base64, "base64"));
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
-  return bytes;
-}

package/src/index.ts

@@ -1,14 +0,0 @@
-export * from "./Engine.js";
-export * from "./EngineConfig.js";
-export * from "./EngineLoop.js";
-export * from "./Time.js";
-export * from "./FixedStepAccumulator.js";
-export * from "./EventBus.js";
-export * from "./Scheduler.js";
-export * from "./TaskQueue.js";
-export * from "./Logger.js";
-export * from "./Diagnostics.js";
-export * from "./Errors.js";
-export * from "./Disposable.js";
-export * from "./ResourceScope.js";
-export * from "./VersionedSerialization.js";