@aura3d/core 1.0.6

package/README.md

@@ -0,0 +1,51 @@
+# @aura3d/core
+
+`@aura3d/core` owns the engine lifecycle, scheduling spine, deterministic time stepping, diagnostics, events, logging, task queues, and disposable resource scopes. It is the root runtime package and does not depend on scene, rendering, physics, animation, assets, input, audio, scripting, editor, or browser-only APIs.
+
+## Public API
+
+- `Engine`: lifecycle owner for plugin initialization, scheduler execution, manual stepping, start/stop control, events, diagnostics, task queues, and resource disposal.
+- `EngineConfig`, `resolveEngineConfig`, `ResolvedEngineConfig`: validated runtime configuration for fixed-step timing, max frame delta, time scale, and optional auto-start behavior.
+- `EngineLoop`, `FrameContext`: deterministic frame loop used by `Engine` for manual and requestAnimationFrame-backed execution.
+- `FixedStepAccumulator`: fixed-step accumulator with max-step clamping for deterministic simulation phases.
+- `Scheduler`, `SystemPhase`: explicit ordered phase scheduler with dependency validation, duplicate rejection, cycle detection, and cross-phase dependency rejection.
+- `TaskQueue`: async-safe queue flushed in the engine task phase.
+- `EventBus`: typed event emitter used by engine lifecycle, frame, and error signals.
+- `Diagnostics`: structured metric/counter snapshot support.
+- `Logger`: scoped runtime logging abstraction.
+- `DisposableStack`, `ResourceScope`: deterministic LIFO cleanup primitives.
+- `VersionedSchema`, `MigrationRegistry`, `SaveSlot`: browser-independent schema validation, save-data migration, and save-slot metadata/data snapshots.
+- `ValidationError`, `LifecycleError`: typed error classes for invalid configuration, graph, and lifecycle operations.
+
+## Lifecycle Contract
+
+An `Engine` starts in `created`. Plugins may only be registered in this state. Calling `init()` transitions through `initializing` into `initialized`, invoking plugin `init` handlers in registration order. If any plugin initialization fails, already initialized plugin disposers run in reverse order and the engine transitions to `failed`.
+
+Calling `start()` is valid only from `initialized` or `stopped`; it starts the configured loop and transitions to `running`. Calling `stop()` from `running` stops the loop and transitions to `stopped`. Calling `step(delta)` from `created` initializes the engine first, then executes one deterministic frame from `initialized`, `running`, or `stopped`.
+
+Each frame executes phases in this order:
+
+1. `Platform`
+2. `Tasks`
+3. queued `TaskQueue` work
+4. `Fixed`, once per accumulated fixed step
+5. `Update`
+6. `Scene`
+7. `Render`
+8. `Present`
+9. `Cleanup`
+
+Calling `dispose()` is idempotent. If the engine is running it stops first, then disposes plugin resources and engine-owned `ResourceScope` entries, clears events, and transitions to `disposed`. Disposal errors are reported as an `AggregateError`.
+
+## Verification
+
+Lifecycle, scheduler, fixed-step, plugin rollback, deterministic manual stepping, and frame diagnostics are covered by:
+
+- `tests/unit/core/scheduler-engine.test.ts`
+- `tests/unit/core/config-time.test.ts`
+- `tests/unit/core/events-disposal-diagnostics.test.ts`
+- `tests/unit/core/versioned-serialization.test.ts`
+- `tests/integration/engine-loop.test.ts`
+- `tests/browser/core-raf-loop.spec.ts`
+
+Public export and import boundaries are covered by `pnpm verify:exports`, `pnpm verify:imports`, and `pnpm verify:boundaries`.

package/dist/Diagnostics.d.ts

@@ -0,0 +1,25 @@
+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;
+}
+export declare class Diagnostics {
+    private readonly maxHistory;
+    private readonly metrics;
+    private readonly activeTimers;
+    constructor(maxHistory?: number);
+    increment(name: string, amount?: number): void;
+    gauge(name: string, value: number): void;
+    begin(name: string): void;
+    end(name: string): number;
+    snapshot(): DiagnosticsSnapshot;
+    private ensure;
+    private recordSample;
+}
+//# sourceMappingURL=Diagnostics.d.ts.map

package/dist/Diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Diagnostics.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/Diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAQD,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,UAAU;IAHvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;gBAE7B,UAAU,SAAM;IAE7C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,IAAI;IAMzC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAMxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAWzB,QAAQ,IAAI,mBAAmB;IAU/B,OAAO,CAAC,MAAM;IAWd,OAAO,CAAC,YAAY;CAIrB"}

package/dist/Diagnostics.js

@@ -0,0 +1,60 @@
+export class Diagnostics {
+    maxHistory;
+    metrics = new Map();
+    activeTimers = new Map();
+    constructor(maxHistory = 120) {
+        this.maxHistory = maxHistory;
+    }
+    increment(name, amount = 1) {
+        const metric = this.ensure(name, "counter");
+        metric.value += amount;
+        this.recordSample(metric, metric.value);
+    }
+    gauge(name, value) {
+        const metric = this.ensure(name, "gauge");
+        metric.value = value;
+        this.recordSample(metric, value);
+    }
+    begin(name) {
+        if (this.activeTimers.has(name))
+            throw new Error(`Timer ${name} already started.`);
+        this.activeTimers.set(name, performance.now());
+    }
+    end(name) {
+        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() {
+        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() });
+    }
+    ensure(name, kind) {
+        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 = { kind, value: 0, samples: [] };
+        this.metrics.set(name, metric);
+        return metric;
+    }
+    recordSample(metric, value) {
+        metric.samples.push(value);
+        if (metric.samples.length > this.maxHistory)
+            metric.samples.shift();
+    }
+}
+//# sourceMappingURL=Diagnostics.js.map

package/dist/Diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Diagnostics.js","sourceRoot":"","sources":["../../../../packages/core/src/Diagnostics.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,WAAW;IAIO;IAHZ,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC3C,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1D,YAA6B,aAAa,GAAG;QAAhB,eAAU,GAAV,UAAU,CAAM;IAAG,CAAC;IAEjD,SAAS,CAAC,IAAY,EAAE,MAAM,GAAG,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC;QACvB,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,IAAY,EAAE,KAAa;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC1C,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,IAAY;QAChB,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAC;QACnF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,GAAG,CAAC,IAAY;QACd,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAC;QAC3E,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC;QACxB,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACpC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,QAAQ;QACN,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;YAChF,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI;YACJ,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;SAC5C,CAAC,CAAC,CAAC;QACJ,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnF,CAAC;IAEO,MAAM,CAAC,IAAY,EAAE,IAAgB;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,sBAAsB,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;YAClG,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,MAAM,GAAkB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,YAAY,CAAC,MAAqB,EAAE,KAAa;QACvD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU;YAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACtE,CAAC;CACF"}

package/dist/Disposable.d.ts

@@ -0,0 +1,12 @@
+export interface Disposable {
+    dispose(): void | Promise<void>;
+}
+export declare function isDisposable(value: unknown): value is Disposable;
+export declare class DisposableStack implements Disposable {
+    private readonly entries;
+    private disposed;
+    use<T extends Disposable>(resource: T): T;
+    get size(): number;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=Disposable.d.ts.map

package/dist/Disposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Disposable.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/Disposable.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,qBAAa,eAAgB,YAAW,UAAU;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAS;IAEzB,GAAG,CAAC,CAAC,SAAS,UAAU,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAQzC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB/B"}

package/dist/Disposable.js

@@ -0,0 +1,37 @@
+export function isDisposable(value) {
+    return typeof value === "object" && value !== null && "dispose" in value && typeof value.dispose === "function";
+}
+export class DisposableStack {
+    entries = [];
+    disposed = false;
+    use(resource) {
+        if (this.disposed) {
+            throw new Error("Cannot add a disposable to an already disposed stack.");
+        }
+        this.entries.push(resource);
+        return resource;
+    }
+    get size() {
+        return this.entries.length;
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const errors = [];
+        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.");
+    }
+}
+//# sourceMappingURL=Disposable.js.map

package/dist/Disposable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Disposable.js","sourceRoot":"","sources":["../../../../packages/core/src/Disposable.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,IAAI,OAAQ,KAAoB,CAAC,OAAO,KAAK,UAAU,CAAC;AAClI,CAAC;AAED,MAAM,OAAO,eAAe;IACT,OAAO,GAAiB,EAAE,CAAC;IACpC,QAAQ,GAAG,KAAK,CAAC;IAEzB,GAAG,CAAuB,QAAW;QACnC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAErB,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YACxB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;IAC7F,CAAC;CACF"}

package/dist/Engine.d.ts

@@ -0,0 +1,46 @@
+import { type FrameContext } from "./EngineLoop.js";
+import { type EngineConfig, type ResolvedEngineConfig } from "./EngineConfig.js";
+import { EventBus } from "./EventBus.js";
+import { Diagnostics } from "./Diagnostics.js";
+import { Logger } from "./Logger.js";
+import { ResourceScope } from "./ResourceScope.js";
+import { Scheduler } 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 declare class Engine {
+    readonly config: ResolvedEngineConfig;
+    readonly events: EventBus<EngineEvents>;
+    readonly diagnostics: Diagnostics;
+    readonly logger: Logger;
+    readonly scheduler: Scheduler;
+    readonly tasks: TaskQueue;
+    readonly resources: ResourceScope;
+    private readonly plugins;
+    private readonly pluginDisposables;
+    private readonly loop;
+    private stateValue;
+    constructor(config?: EngineConfig);
+    get state(): EngineState;
+    use(plugin: EnginePlugin): this;
+    init(): Promise<void>;
+    start(): void;
+    stop(): void;
+    step(delta: number): Promise<FrameContext>;
+    dispose(): Promise<void>;
+    private runFrame;
+    private setState;
+}
+//# sourceMappingURL=Engine.d.ts.map

package/dist/Engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/Engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAuB,KAAK,YAAY,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEtG,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,cAAc,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAErH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC;IAChF,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,qBAAa,MAAM;IACjB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,yBAA2E;IAC1F,QAAQ,CAAC,WAAW,cAAqB;IACzC,QAAQ,CAAC,MAAM,SAAgB;IAC/B,QAAQ,CAAC,SAAS,YAAmB;IACrC,QAAQ,CAAC,KAAK,YAAmB;IACjC,QAAQ,CAAC,SAAS,gBAA+B;IAEjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,UAAU,CAA0B;gBAEhC,MAAM,GAAE,YAAiB;IAWrC,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAOzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,IAAI;IAMN,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ1C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAmBhB,QAAQ;IAgBtB,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/Engine.js

@@ -0,0 +1,130 @@
+import { DisposableStack } from "./Disposable.js";
+import { EngineLoop } from "./EngineLoop.js";
+import { resolveEngineConfig } 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 class Engine {
+    config;
+    events = new EventBus((error) => this.events.emit("error", error));
+    diagnostics = new Diagnostics();
+    logger = new Logger();
+    scheduler = new Scheduler();
+    tasks = new TaskQueue();
+    resources = new ResourceScope("engine");
+    plugins = [];
+    pluginDisposables = new DisposableStack();
+    loop;
+    stateValue = "created";
+    constructor(config = {}) {
+        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() {
+        return this.stateValue;
+    }
+    use(plugin) {
+        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() {
+        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() {
+        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() {
+        if (this.stateValue !== "running")
+            return;
+        this.loop.stop();
+        this.setState("stopped");
+    }
+    async step(delta) {
+        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() {
+        if (this.stateValue === "disposed")
+            return;
+        if (this.stateValue === "running")
+            this.stop();
+        const errors = [];
+        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.");
+    }
+    async runFrame(context) {
+        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);
+    }
+    setState(next) {
+        const previous = this.stateValue;
+        this.stateValue = next;
+        this.events.emit("stateChanged", Object.freeze({ previous, current: next }));
+    }
+}
+//# sourceMappingURL=Engine.js.map

package/dist/Engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Engine.js","sourceRoot":"","sources":["../../../../packages/core/src/Engine.ts"],"names":[],"mappings":"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"}

package/dist/EngineConfig.d.ts

@@ -0,0 +1,18 @@
+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 declare function resolveEngineConfig(config?: EngineConfig): ResolvedEngineConfig;
+//# sourceMappingURL=EngineConfig.d.ts.map

package/dist/EngineConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineConfig.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/EngineConfig.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,YAAiB,GAAG,oBAAoB,CAiBnF"}

package/dist/EngineConfig.js

@@ -0,0 +1,23 @@
+import { ValidationError } from "./Errors.js";
+export function resolveEngineConfig(config = {}) {
+    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);
+}
+//# sourceMappingURL=EngineConfig.js.map

package/dist/EngineConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineConfig.js","sourceRoot":"","sources":["../../../../packages/core/src/EngineConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAoB9C,MAAM,UAAU,mBAAmB,CAAC,SAAuB,EAAE;IAC3D,MAAM,QAAQ,GAAG;QACf,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE;QACjC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,CAAC,GAAG,EAAE;QACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,CAAC;QACxC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,CAAC;QAChC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,KAAK;KACrC,CAAC;IAEF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,SAAS,IAAI,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,oBAAoB,EAAE,6BAA6B,CAAC,CAAC;IACpJ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,UAAU,IAAI,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,qBAAqB,EAAE,8BAA8B,CAAC,CAAC;IACxJ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,IAAI,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,mBAAmB,EAAE,4BAA4B,CAAC,CAAC;IAChJ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,aAAa,IAAI,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,yBAAyB,EAAE,2CAA2C,CAAC,CAAC;IAChL,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,SAAS,GAAG,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,oBAAoB,EAAE,4CAA4C,CAAC,CAAC;IAElK,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/dist/EngineLoop.d.ts

@@ -0,0 +1,33 @@
+import { 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 declare class EngineLoop {
+    private readonly options;
+    private readonly onFrame;
+    private readonly time;
+    private readonly accumulator;
+    private running;
+    private rafHandle;
+    private lastTimestamp;
+    constructor(options: EngineLoopOptions, onFrame: FrameCallback);
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    step(delta: number): Promise<FrameContext>;
+    snapshot(): TimeSnapshot;
+    private tickRaf;
+}
+//# sourceMappingURL=EngineLoop.d.ts.map

package/dist/EngineLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineLoop.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/EngineLoop.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,UAAU;IAQnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;IACnD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,aAAa,CAAqB;gBAGvB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,aAAa;IAMzC,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;IASZ,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,IAAI;IAIR,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQhD,QAAQ,IAAI,YAAY;YAIV,OAAO;CAOtB"}

package/dist/EngineLoop.js

@@ -0,0 +1,63 @@
+import { FixedStepAccumulator } from "./FixedStepAccumulator.js";
+import { Time } from "./Time.js";
+export class EngineLoop {
+    options;
+    onFrame;
+    time;
+    accumulator;
+    running = false;
+    rafHandle;
+    lastTimestamp;
+    constructor(options, onFrame) {
+        this.options = options;
+        this.onFrame = onFrame;
+        this.time = new Time(options.maxDelta, options.timeScale ?? 1);
+        this.accumulator = new FixedStepAccumulator(options.fixedDelta, options.maxFixedSteps);
+    }
+    start() {
+        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() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.rafHandle !== undefined && typeof cancelAnimationFrame === "function") {
+            cancelAnimationFrame(this.rafHandle);
+        }
+        this.rafHandle = undefined;
+    }
+    pause() {
+        this.stop();
+    }
+    resume() {
+        this.start();
+    }
+    async step(delta) {
+        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() {
+        return this.time.snapshot();
+    }
+    async tickRaf(timestamp) {
+        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));
+    }
+}
+//# sourceMappingURL=EngineLoop.js.map

package/dist/EngineLoop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngineLoop.js","sourceRoot":"","sources":["../../../../packages/core/src/EngineLoop.ts"],"names":[],"mappings":"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"}

package/dist/Errors.d.ts

@@ -0,0 +1,14 @@
+export declare class EngineError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare class LifecycleError extends EngineError {
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare class ValidationError extends EngineError {
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare class ResourceError extends EngineError {
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=Errors.d.ts.map

package/dist/Errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Errors.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/Errors.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,qBAAa,cAAe,SAAQ,WAAW;gBACjC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGlE;AAED,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGlE;AAED,qBAAa,aAAc,SAAQ,WAAW;gBAChC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGlE"}

package/dist/Errors.js

@@ -0,0 +1,24 @@
+export class EngineError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+export class LifecycleError extends EngineError {
+    constructor(code, message, options) {
+        super(`LIFECYCLE_${code}`, message, options);
+    }
+}
+export class ValidationError extends EngineError {
+    constructor(code, message, options) {
+        super(`VALIDATION_${code}`, message, options);
+    }
+}
+export class ResourceError extends EngineError {
+    constructor(code, message, options) {
+        super(`RESOURCE_${code}`, message, options);
+    }
+}
+//# sourceMappingURL=Errors.js.map

package/dist/Errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Errors.js","sourceRoot":"","sources":["../../../../packages/core/src/Errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,WAAY,SAAQ,KAAK;IAEzB;IADX,YACW,IAAY,EACrB,OAAe,EACf,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAJf,SAAI,GAAJ,IAAI,CAAQ;QAKrB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,WAAW;IAC7C,YAAY,IAAY,EAAE,OAAe,EAAE,OAAsB;QAC/D,KAAK,CAAC,aAAa,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C,YAAY,IAAY,EAAE,OAAe,EAAE,OAAsB;QAC/D,KAAK,CAAC,cAAc,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C,YAAY,IAAY,EAAE,OAAe,EAAE,OAAsB;QAC/D,KAAK,CAAC,YAAY,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;CACF"}

package/dist/EventBus.d.ts

@@ -0,0 +1,18 @@
+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 declare class EventBus<TEvents extends EventMapBase> {
+    private readonly onListenerError?;
+    private readonly listeners;
+    private readonly onceListeners;
+    constructor(onListenerError?: EventErrorHandler | undefined);
+    on<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): Subscription;
+    once<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): Subscription;
+    off<K extends keyof TEvents>(eventName: K, listener: EventListener<TEvents[K]>): void;
+    emit<K extends keyof TEvents>(eventName: K, event: TEvents[K]): void;
+    clear(): void;
+}
+//# sourceMappingURL=EventBus.d.ts.map

package/dist/EventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/EventBus.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAClD,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,qBAAa,QAAQ,CAAC,OAAO,SAAS,YAAY;IAIpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IAH7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwE;IAClG,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwD;gBAEzD,eAAe,CAAC,EAAE,iBAAiB,YAAA;IAEhE,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY;IAO5F,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY;IAM9F,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAMrF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAepE,KAAK,IAAI,IAAI;CAGd"}