@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/adapter/rapier-physics-adapter.js

@@ -0,0 +1,46 @@
+/**
+ * RapierPhysicsAdapter — the first-party `PhysicsAdapter` over the existing
+ * `PhysicsRegistry` (Object3D ↔ Rapier body/collider). This is the generalized,
+ * behind-the-interface form of the old `setEcsSyncTransform` teleport: it lets
+ * the editor freeze a body, apply a gizmo edit, and resume — without the editor
+ * knowing Rapier exists.
+ */
+export function createRapierPhysicsAdapter(registry, debugMesh) {
+    /** Saved body types while frozen, so unfreeze can restore them. */
+    const frozen = new Map();
+    return {
+        ownerOf(o) {
+            const body = registry.get(o)?.body;
+            if (!body)
+                return 'editor';
+            // A fixed body never moves on its own → the editor owns its transform.
+            return body.isFixed() ? 'editor' : 'physics';
+        },
+        freeze(o) {
+            const body = registry.get(o)?.body;
+            if (!body || frozen.has(body))
+                return;
+            frozen.set(body, body.bodyType());
+            // Kinematic-position: the body stops simulating but tracks the pose we set.
+            body.setBodyType(2 /* KinematicPositionBased */, true);
+        },
+        commit(o, t) {
+            const body = registry.get(o)?.body;
+            if (!body)
+                return;
+            body.setTranslation({ x: t.position[0], y: t.position[1], z: t.position[2] }, true);
+            body.setRotation({ x: t.rotation[0], y: t.rotation[1], z: t.rotation[2], w: t.rotation[3] }, true);
+        },
+        unfreeze(o) {
+            const body = registry.get(o)?.body;
+            if (!body)
+                return;
+            const prev = frozen.get(body);
+            if (prev !== undefined) {
+                body.setBodyType(prev, true);
+                frozen.delete(body);
+            }
+        },
+        debugDraw: () => debugMesh ?? null,
+    };
+}

package/dist/adapter/system-adapter.d.ts

@@ -0,0 +1,206 @@
+/**
+ * System adapters — optional subsystem capability providers hung off a mounted
+ * game (`MountedGame.systems`). Each is a thin capability boundary the editor can
+ * coordinate with WITHOUT owning the implementation. The first-party
+ * implementers wrap Rapier / Colyseus / the InputManager; an external game
+ * supplies its own or none, and the editor degrades per `capabilities`.
+ *
+ * These are introspection/coordination boundaries, NOT re-implementations: e.g.
+ * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
+ * Rapier — it lets the editor ask "who owns this object" and "freeze it while I
+ * edit it".
+ */
+import type * as THREE from 'three';
+import type { ActionValueType, Vector2 } from '../input/input-types';
+import type { Transform, TransformOwner } from './transform';
+/**
+ * Physics coordination so the editor can stably edit an object a simulation
+ * would otherwise overwrite every frame: `freeze → apply → unfreeze`.
+ */
+export interface PhysicsAdapter {
+    /** Returns `'physics'` when a body drives this object, else another owner. */
+    ownerOf(o: THREE.Object3D): TransformOwner;
+    /** Pause the body driving `o` (kinematic / sleep / detach) for editing. */
+    freeze(o: THREE.Object3D): void;
+    /** Teleport the body to the edited pose (so the sim continues from there). */
+    commit(o: THREE.Object3D, t: Transform): void;
+    /** Resume simulation of `o`. */
+    unfreeze(o: THREE.Object3D): void;
+    /** Optional debug-draw object (collider wireframes). */
+    debugDraw?(): THREE.Object3D | null;
+}
+export interface NetPeer {
+    id: string;
+    label?: string;
+}
+/** The live connection lifecycle, for the editor's network inspector. */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** Identity of the room the local peer is currently in, or `null` when not connected. */
+export interface RoomInfo {
+    roomId: string;
+    sessionId: string;
+    roomName: string;
+}
+/** Lightweight replication counters for the editor's network inspector. */
+export interface ReplicationStats {
+    /** Number of replicated entities currently known (e.g. players + NPCs). */
+    entities: number;
+    /** Approximate inbound replication activity (state changes observed per second). */
+    msgsInPerSec: number;
+    /** Approximate outbound message rate (client → server sends per second). */
+    msgsOutPerSec: number;
+}
+export type Unsubscribe = () => void;
+/** INTROSPECTION over replication state — NOT a networking transport. */
+export interface NetworkingAdapter {
+    peers(): NetPeer[];
+    networkId(o: THREE.Object3D): string | null;
+    authority(o: THREE.Object3D): 'local' | 'remote' | 'server';
+    /** Remote/server-authoritative objects → inspect-only in the editor. */
+    editable(o: THREE.Object3D): boolean;
+    /** Current connection lifecycle state. */
+    getConnectionState(): ConnectionState;
+    /** The active room's identity, or `null` when not connected to a room. */
+    getRoomInfo(): RoomInfo | null;
+    /** Replication activity snapshot, for a live network inspector panel. */
+    getReplicationStats(): ReplicationStats;
+    /** Subscribe to changes in connection state / room / replication stats. */
+    subscribe(cb: () => void): Unsubscribe;
+}
+/** One action's current value, tagged with its declared shape (F1 `ActionValueType`) so a
+ *  consumer (editor input inspector, conformance suite) can render/assert on the real typed
+ *  value instead of a lossy digital coercion. `value` is a `number` for `'digital'`
+ *  (1 = pressed, 0 = not) and `'scalar'`, or a `Vector2` for `'vector2'`/`'pointerDelta'`/
+ *  `'pointerPosition'` — narrow on `type` to know which. */
+export interface ActionValueSnapshot {
+    type: ActionValueType;
+    value: number | Vector2;
+}
+export interface InputAdapter {
+    poll(): void;
+    /** Every named action's current value, faithfully typed per its declared `ActionValueType`
+     *  (F1, spec §12) — digital reads as 1/0, scalar as its float, vector2/pointerDelta/
+     *  pointerPosition as `{x,y}`. Never coerces a non-digital action down to 0/1. */
+    actions(): Readonly<Record<string, ActionValueSnapshot>>;
+}
+/** URL remap so an ingested game's relative asset paths resolve under the host. */
+export interface AssetAdapter {
+    resolve(url: string): string;
+}
+export interface NavPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Inspect a game's navigation mesh: whether one is built, query a path, and get a
+ * debug overlay. Coordination/introspection only — the editor doesn't own the build.
+ */
+export interface NavigationAdapter {
+    hasNavMesh(): boolean;
+    findPath(start: NavPoint, end: NavPoint): NavPoint[];
+    debugMesh(scene: THREE.Scene): THREE.Object3D | null;
+}
+/**
+ * Silence/restore a world's own audio (D10, T7.6) — NOT a mixer/bus API. This
+ * is the seam `Game.play.pause()` calls so a paused world's audio goes quiet
+ * too (`docs/DECISIONS-PENDING.md` §D10: "an audio seam in `SystemAdapters` so
+ * pause can silence game audio (howler et al.) or explicitly report it
+ * cannot"). Absence on a world's `mounted.systems` means exactly that:
+ * `Game.play.pause()` reports it loudly once per world rather than silently
+ * leaving that world's audio playing under a "paused" game.
+ */
+export interface AudioAdapter {
+    /** `true` silences this world's audio; `false` restores it to whatever
+     *  level it was at before silencing (an implementer's own concern — the
+     *  first-party adapter restores its master-gain value, not a hardcoded 1). */
+    setMuted(muted: boolean): void;
+    /** Current muted state, for inspection (editor mute UI, proofs). */
+    isMuted(): boolean;
+}
+/** One tick-stamped debug event (`ctx.debug.emit`, spec §3.3): `tick`/`simT`
+ *  are the engine's own counters AT EMISSION, so events and state reads
+ *  correlate frame-exactly across every door (in-page bridge, relay, panels).
+ *
+ *  `seq` (run-4 friction #5 fix) is a registry-lifetime MONOTONIC counter,
+ *  strictly increasing by one per `emit()` call regardless of `tick` —
+ *  unlike `tick`, it is never shared by two events, which is what makes it
+ *  safe to fence on. A debug command handler runs BETWEEN ticks (its
+ *  emissions carry whatever `tick` is current at that instant, same as every
+ *  other emission at that instant would), so two DIFFERENT events — or an
+ *  event and a consumer's fence point — can legitimately share one `tick`;
+ *  `seq` never collides the same way, so "everything after what I've already
+ *  observed" is unambiguous. See `events(sinceTick, sinceSeq)` below. */
+export interface TickStampedEvent {
+    tick: number;
+    simT: number;
+    event: string;
+    detail?: unknown;
+    seq: number;
+}
+/** One registered debug command's listing shape — `locus` is always present
+ *  (defaults to `'client'` when a command didn't declare one) so every
+ *  listing surface can print it without a fallback of its own. */
+export interface DebugCommandInfo {
+    name: string;
+    description?: string | undefined;
+    /** JSON-Schema projection of the command's Zod args tuple, when declared. */
+    argsJsonSchema?: unknown;
+    locus: 'client' | 'server';
+}
+/**
+ * The debug/synthetic-player seam (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.1):
+ * game-scoped introspection + actuation over whatever a game registers via
+ * `ctx.debug` (`registerStateProvider`/`registerCommand`/`emit`). NOT a
+ * gameplay API — this is the one seam the debug bridge, the editor's Debug
+ * Console/State Watch panels, and `@vgai/probe` all read/drive through.
+ */
+export interface DebugAdapter {
+    providers(): {
+        name: string;
+        tier: 'observable' | 'assisted';
+    }[];
+    /** One provider's current value. Throws `DebugError` code
+     *  `STATE_PROVIDER_NOT_FOUND` (`data.registered`) for an unknown name. */
+    state(name: string): unknown;
+    /** One coherent snapshot of every registered provider — a throwing
+     *  provider contributes `{ __error: String(err) }` for its own key rather
+     *  than failing the whole snapshot. */
+    stateAll(): Record<string, unknown>;
+    commands(): DebugCommandInfo[];
+    /** Validates `args` against the command's declared Zod tuple (when
+     *  present), then awaits the registered fn. Throws `DebugError` code
+     *  `DEBUG_COMMAND_NOT_REGISTERED` for an unknown name,
+     *  `DEBUG_COMMAND_ARGS_INVALID` for a validation failure, or
+     *  `DEBUG_COMMAND_FAILED` wrapping anything the command itself threw. */
+    invoke(name: string, args: unknown[]): Promise<unknown>;
+    /** The tick-stamped event ring (cap 500, drops oldest).
+     *
+     *  - `sinceSeq` given (run-4 friction #5 fix): filters to `seq > sinceSeq`
+     *    — the unambiguous fence a consumer should use to mean "everything
+     *    emitted after what I've already observed" (see `TickStampedEvent.seq`'s
+     *    doc comment for why `tick` alone can't do this: a debug-command
+     *    emission and a consumer's fence point can share one tick, and the
+     *    old `tick > sinceTick` filter silently dropped same-tick events).
+     *    Takes precedence over `sinceTick` when both are given.
+     *  - `sinceTick` only: the ORIGINAL (pre-fix) filter, `tick > sinceTick` —
+     *    kept for back-compat callers that only ever had a tick to fence on;
+     *    still has the same-tick blind spot by construction, so a new caller
+     *    should prefer `sinceSeq`.
+     *  - Neither given: the whole ring. */
+    events(sinceTick?: number, sinceSeq?: number): TickStampedEvent[];
+}
+/**
+ * The set of optional subsystem providers a mounted game may expose. Absence of
+ * a provider means "capability not supported" — the editor degrades gracefully.
+ */
+export interface SystemAdapters {
+    physics?: PhysicsAdapter;
+    networking?: NetworkingAdapter;
+    input?: InputAdapter;
+    assets?: AssetAdapter;
+    navigation?: NavigationAdapter;
+    audio?: AudioAdapter;
+    debug?: DebugAdapter;
+}
+//# sourceMappingURL=system-adapter.d.ts.map

package/dist/adapter/system-adapter.d.ts.map

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

package/dist/adapter/system-adapter.js

@@ -0,0 +1,13 @@
+/**
+ * System adapters — optional subsystem capability providers hung off a mounted
+ * game (`MountedGame.systems`). Each is a thin capability boundary the editor can
+ * coordinate with WITHOUT owning the implementation. The first-party
+ * implementers wrap Rapier / Colyseus / the InputManager; an external game
+ * supplies its own or none, and the editor degrades per `capabilities`.
+ *
+ * These are introspection/coordination boundaries, NOT re-implementations: e.g.
+ * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
+ * Rapier — it lets the editor ask "who owns this object" and "freeze it while I
+ * edit it".
+ */
+export {};

package/dist/adapter/transform.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The neutral transform value used across adapter interfaces. Position + scale
+ * are xyz; rotation is a quaternion (xyzw) — matching `Object3D.quaternion`, so
+ * adapters never have to agree on an Euler convention.
+ */
+export interface Transform {
+    position: [number, number, number];
+    rotation: [number, number, number, number];
+    scale: [number, number, number];
+}
+/**
+ * Who currently owns an object's transform — i.e. what writes it each frame.
+ * The editor uses this to decide whether a gizmo edit is durable (`editor`),
+ * needs simulation coordination (`physics`), or is best-effort/inspect-only
+ * (`script`/`network`/`external`).
+ */
+export type TransformOwner = 'editor' | 'physics' | 'animation' | 'script' | 'network' | 'external';
+//# sourceMappingURL=transform.d.ts.map

package/dist/adapter/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/adapter/transform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC"}

package/dist/adapter/transform.js

@@ -0,0 +1 @@
+export {};

package/dist/adapter/vgai-scene-game-adapter.d.ts

@@ -0,0 +1,108 @@
+/**
+ * VgaiSceneGameAdapter — the FIRST-PARTY implementer of {@link GameAdapter}.
+ *
+ * This is where `.vscn` + `GameComponent` + Rapier live now: the host no longer
+ * knows about any of them. `mount(host)` builds the full first-party runtime
+ * (the body that used to live inline in `create-runtime.ts`) from a neutral
+ * {@link HostContext}, runs the game's `setup`/scene load, and returns a
+ * {@link MountedGame}. First-party content is now just one implementer of the
+ * same interface an unmodified external game implements (Phase B).
+ *
+ * `GameSetupFn` / `GameContext` are imported ONLY here (and in the example
+ * `fromSetup` wrappers) — never by the host. That confinement is the inversion.
+ */
+import type { EffectComposer } from 'postprocessing';
+import * as THREE from 'three';
+import type { WorldFrameHooks } from '../runtime/game';
+import type { EditorPreview, GameContext, GameSetupFn } from '../runtime/types';
+import type { ComponentRegistry } from '../scene/component-registry';
+import { type SceneInstance } from '../scene/scene-loader';
+import type { SceneFile } from '../scene/scene-types';
+import type { GameAdapter, MountedGame } from './game-adapter';
+import type { HostContext } from './host-context';
+/** How a {@link VgaiSceneGameAdapter} builds its game (the former RuntimeConfig). */
+export interface VgaiSceneConfig {
+    /** Game setup function — registers systems and loads scenes. */
+    setup?: GameSetupFn | undefined;
+    /** Editor context — passed to setup() when launched from the editor. */
+    editorPreview?: EditorPreview | undefined;
+    /** Path to a .vscn.json scene file. Loaded if no setup is provided. */
+    scenePath?: string | undefined;
+    /** In-memory scene data. Loaded if no setup and no scenePath is provided. */
+    sceneData?: SceneFile | undefined;
+    /**
+     * Component name -> GameComponent class map, threaded into the scene
+     * loader's `SceneLoadContext.componentRegistry` for both the `scenePath`
+     * and `sceneData` branches (never for `setup` — a custom setup already
+     * owns its own registry, e.g. `template/src/scripts/main.ts`'s generic
+     * fallback). Without this, a scene's `components:` entries throw
+     * ("Component ... not found in registry") or, pre-T7.2-closure, were
+     * simply unreachable through these two config options at all (the T7.2
+     * finding `docs/CLI-ON-FOLDER-DESIGN.md` §1D calls out — see
+     * `packages/editor/src/adapter-resolver.ts`, the only production caller
+     * that sets this today).
+     */
+    componentRegistry?: ComponentRegistry | undefined;
+    /** Input map JSON path. Defaults to 'inputmaps/default.inputmap.json'. */
+    inputMapPath?: string | undefined;
+    /** URL prefix for relative asset paths. Defaults to '/'. */
+    assetPrefix?: string | undefined;
+    /** Stable adapter id (for registry/conformance). Defaults to 'vgai-scene'. */
+    id?: string | undefined;
+}
+/**
+ * The first-party `MountedGame`, with concrete extras the editor host uses for
+ * first-party features (HMR, physics sync) that are NOT part of the neutral
+ * interface. The generic host only touches the `MountedGame` surface.
+ */
+export interface VgaiMountedGame extends MountedGame {
+    /**
+     * First-party brand (checklist item 1 / T7.3 lookahead): a plain `'ctx' in
+     * mounted` structural check misfires once world2d's `MountedGame2D`
+     * (`world2d/pixi-game-adapter.ts`) also has a `ctx` key — its `ctx` is a
+     * `World2DContext`, not a `GameContext`, and has none of
+     * `queryByComponent`/`physics`/`collisions`/`camera`. This literal-`true`
+     * property is what `isFirstPartyMounted` (`runtime/game.ts`) actually
+     * checks; `game.ts` reads it via a structural `{ firstParty?: unknown }`
+     * probe so it never needs a value import of this module (the existing
+     * import is type-only and must stay that way).
+     */
+    readonly firstParty: true;
+    readonly ctx: GameContext;
+    readonly composer: EffectComposer | null;
+    /** Warm-restart: dispose the current game, re-run a new setup on the same ctx. */
+    hotReload(newSetup: GameSetupFn, editorPreview?: EditorPreview): Promise<void>;
+    /**
+     * Phase-partitioned frame entry point (T7.1 slice 2,
+     * `docs/GAME-ROOT-DESIGN.md` §4) — wired onto this world's `WorldInstance`
+     * by `registerThreeWorld` (`create-runtime.ts`). `Game.runFrame` is
+     * the CANONICAL driver going forward: it calls `frame.runPhase` once per
+     * (phase, substep) for every world, then `frame.endFrame` once per
+     * substep after all roots finish all phases. `update` (below) remains
+     * the legacy/direct entry point to the exact same `SystemRunner` — direct
+     * callers (editor HMR, adapter conformance tests) keep using it unchanged.
+     */
+    readonly frame: WorldFrameHooks;
+}
+/**
+ * Wrap a first-party `setup` function as a {@link GameAdapter}. This is how every
+ * first-party example becomes an implementer of the same interface an external
+ * game implements — with no change to the setup's body.
+ */
+export declare function fromSetup(id: string, setup: GameSetupFn): GameAdapter;
+export declare class VgaiSceneGameAdapter implements GameAdapter {
+    private readonly config;
+    readonly id: string;
+    constructor(config?: VgaiSceneConfig);
+    mount(host: HostContext): Promise<VgaiMountedGame>;
+}
+/** The pose `adoptSceneCamera` compares against to detect that a component
+ *  already framed the runtime camera during scene load (#139). Capture with
+ *  `captureCameraPose(camera)` immediately BEFORE `loadScene`. */
+export interface CameraPose {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+}
+export declare function captureCameraPose(camera: THREE.PerspectiveCamera): CameraPose;
+export declare function adoptSceneCamera(sceneInstance: SceneInstance, runtimeCamera: THREE.PerspectiveCamera, preLoadPose?: CameraPose): boolean;
+//# sourceMappingURL=vgai-scene-game-adapter.d.ts.map

package/dist/adapter/vgai-scene-game-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgai-scene-game-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/vgai-scene-game-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAuB/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAe,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAgBtD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAClC;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAClD,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,8EAA8E;IAC9E,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAeD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAErE;AAED,qBAAa,oBAAqB,YAAW,WAAW;IAE1C,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBACS,MAAM,GAAE,eAAoB;IAKnD,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAupBzD;AAcD;;kEAEkE;AAClE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC;IACxB,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC;CAC9B;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,UAAU,CAE7E;AAED,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,KAAK,CAAC,iBAAiB,EACtC,WAAW,CAAC,EAAE,UAAU,GACvB,OAAO,CAsDT"}