@vgai/engine 0.5.22 → 0.5.24

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

@@ -0,0 +1,168 @@
+/**
+ * `createSystemSlot` — THE implementation of the declared-slot façade, the
+ * seam between a STATIC `systems` declaration and a LIVE adapter that only
+ * exists once the world tree is mounted.
+ *
+ * WHY IT EXISTS. An entry declares its systems statically
+ * (`export const systems = { networking: networkingSystem() }`), while the
+ * thing being declared — a joined Colyseus room, a baked navmesh, a mounted
+ * `<Physics>`, a cutscene's camera ownership — is built inside the world tree,
+ * later, and may be replaced (reconnect, remount, hot restart) or go away
+ * (stop). The slot is a stable object the host installs at mount and holds
+ * forever; every call forwards to whatever is attached right now.
+ *
+ * ── THE HONESTY RULE, STATED IN ONE PLACE ───────────────────────────────────
+ * This is why the pattern is centralized: five hand-rolled copies disagreed
+ * about it, and each disagreement was found by a separate review.
+ *
+ *  - An **action** with no live target REFUSES BY NAME
+ *    (`<name>: <unattachedMessage>`). Never a silent no-op — a caller that
+ *    told the game to DO something must learn that it did not happen. An
+ *    action against a live adapter that lacks the member refuses the same
+ *    way, naming the member.
+ *  - A **read** answers its declared HONEST EMPTY — `'disconnected'`, `[]`,
+ *    `null`, `false`. That is not a fabrication: it is the truth of the
+ *    not-attached state, in the same vocabulary the editor's own edit-mode
+ *    adapters use. Reads are also the only kind safe to call from a per-frame
+ *    debug draw, which is why a throw into a rAF loop is never the answer.
+ *  - An **optional** member MIRRORS THE LIVE ADAPTER'S PRESENCE: absent while
+ *    unattached, and absent afterwards when the live adapter itself does not
+ *    provide it. Presence IS the consume-by-presence protocol's signal, so
+ *    the slot may never invent it. Each presence read CAPTURES the adapter it
+ *    saw and forwards to that same instance, so a detach between the read and
+ *    the call answers as the adapter the caller was handed rather than a
+ *    mid-flight swap.
+ *  - A **subscribe** member SURVIVES REATTACHMENT: listeners live on the
+ *    slot, never on the instance, and the slot re-binds its own single
+ *    subscription on every attach/detach. A panel that subscribed once to the
+ *    stable slot object is therefore never left holding a disposed system, and
+ *    it is notified when the live half appears or disappears.
+ *  - A member the config DOES NOT LIST does not exist on the slot at all.
+ *    That is how the anti-shim rule spells omission — e.g. `PhysicsAdapter`'s
+ *    `debugDraw`/`contactPoints` over `@react-three/rapier`, whose debug line
+ *    segments live inside the fiber tree and expose no handle. Absence is a
+ *    capability answer; a stub is a lie.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: whoever built the live adapter (the hook, the bridge component). The
+ * slot owns only the POINTER to it plus its own listener set and its own
+ * subscription to the live half. SHARERS: every reader of the declared
+ * system — editor inspectors, instruments. TEARDOWN: the function `attach`
+ * returns, and nothing else. It is IDENTITY-GUARDED — it clears only while
+ * the same instance is still attached, so a replace-then-teardown-the-old
+ * ordering cannot detach the new one — and detaching never disposes the
+ * adapter, because the slot did not create it.
+ *
+ * WHERE the slot module lives decides how many games share it. A slot in
+ * PROJECT-owned source (the four capability/example façades) is per Play
+ * instance, because the editor stamps mount ids onto project-owned import
+ * specifiers (`server/project-module-instance.ts`) — N instances get N module
+ * graphs and N slots. A slot in an ENGINE module is reached by bare
+ * specifier, which that stamping deliberately never touches, so it is ONE per
+ * page: every Play instance shares it, and concurrent instances' attaches
+ * contend (last attach wins; the loser's detach is dropped by the identity
+ * guard). `rapier-physics-bridge.tsx` is the one such slot today and warns
+ * loudly when contended — prefer project-owned slot modules for anything new.
+ *
+ * NOT A WRAPPER. The slot's members have the adapter interface's own exact
+ * signatures and hand back the implementation's own values; nothing stands
+ * between a caller and the live library object.
+ */
+import type { VgaiGameSystemEmpty } from './ingest/game-contract';
+/**
+ * `absent(reason)` — THE WHOLE-SLOT counterpart of the four per-member policies
+ * above, and the fifth line of the same honesty rule.
+ *
+ * The four policies answer "this slot exists but nothing is attached yet". This
+ * one answers a different question entirely: **this game will never have that
+ * subsystem, and here is what was searched.** A slot simply left out of the
+ * `systems` table cannot say that — an omitted key means "unsupported", which is
+ * the same shape as "nobody looked", and the coverage report has to file it as a
+ * work order forever. Declaring the absence turns an UNANSWERED row into a
+ * terminal one.
+ *
+ * ```ts
+ * export const systems = {
+ *   audio: sfxAudioSystem(),
+ *   physics: rapierPhysicsSystem(),
+ *   networking: absent('single-player: no Colyseus client anywhere in `src/`'),
+ * };
+ * ```
+ *
+ * ## It is a CONSTRUCTOR for the shape that already exists, not a second one
+ *
+ * The returned value IS `VgaiGameSystemEmpty` — the plain
+ * `{ present: false, evidence }` record an INGESTED game declares on
+ * `window.vgaiGame.systems.systemAdapters`, validated by the same single
+ * projection (`ingest/contract-system-adapters.ts`). There is one shape law, not
+ * two: a foreign game cannot import this helper and must stay able to write the
+ * record by hand, so nothing here may brand the runtime value. What the helper
+ * buys a FIRST-PARTY author is the reason-quality check moved to the call site —
+ * our own code failing its own contract fails fast, where an ingested game's
+ * same mistake is filed as a `malformed` verdict for its coverage report.
+ *
+ * ## It is a MARKER, never a stub adapter
+ *
+ * Do not answer an absent slot with an adapter whose methods return zeros. A
+ * `getConnectionState()` of `'disconnected'` on a game with no transport implies
+ * a connection that could exist; that is the fabrication the anti-shim rule
+ * forbids. The absence is STATED, and the host installs nothing for it.
+ *
+ * @param reason What was searched and what was found, in the game's own source
+ *   terms. "no netcode anywhere in `src/`" is a finished answer a reviewer can
+ *   re-run; "not implemented yet" is a plan, and is rejected here.
+ */
+export declare function absent(reason: string): VgaiGameSystemEmpty;
+/** Any adapter member. `never[]` args make the conditional match contravariantly. */
+type AnyFn = (...args: never[]) => unknown;
+/** The declared member's return type, used to type a `read`'s honest empty. */
+type MemberReturn<F> = NonNullable<F> extends (...args: never[]) => infer R ? R : never;
+/**
+ * The per-member policy. There are exactly four, and every member of every
+ * declared slot in the repo is one of them — see the honesty rule above.
+ */
+export type SystemSlotMemberSpec<F> = {
+    readonly kind: 'action';
+} | {
+    readonly kind: 'read';
+    readonly empty: MemberReturn<F>;
+} | {
+    readonly kind: 'subscribe';
+} | {
+    readonly kind: 'optional';
+};
+/** The keys of `T` whose values are callable (data properties are not slottable). */
+type FunctionMemberKeys<T> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends AnyFn ? K : never;
+}[keyof T];
+/** Per-member policies. A member left out is left OFF the slot entirely. */
+export type SystemSlotMembers<T> = {
+    readonly [K in FunctionMemberKeys<T>]?: SystemSlotMemberSpec<T[K]>;
+};
+export interface SystemSlotConfig<T extends object> {
+    /**
+     * The slot's own name, used as the prefix of every refusal so a stack-less
+     * error still names the seam (`'networkingSystem'`, `'rapierPhysicsSystem'`).
+     */
+    readonly name: string;
+    /**
+     * The rest of an action's refusal while nothing is attached — the DOMAIN
+     * half of the message, naming what has not happened yet ("the world is not
+     * playing, or the navmesh has not finished building").
+     */
+    readonly unattachedMessage: string;
+    readonly members: SystemSlotMembers<T>;
+}
+export interface SystemSlot<T extends object> {
+    /**
+     * Publish `live` as the slot's target. Returns the ONE detach path, which
+     * is identity-guarded: it clears only while `live` is still the attached
+     * instance, and never disposes it.
+     */
+    attach(live: T): () => void;
+    /** The stable declared object. Hand THIS to the entry's `systems` map. */
+    readonly slot: T;
+}
+export declare function createSystemSlot<T extends object>(config: SystemSlotConfig<T>): SystemSlot<T>;
+export {};
+//# sourceMappingURL=system-slot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system-slot.d.ts","sourceRoot":"","sources":["../../src/adapter/system-slot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAS1D;AAED,qFAAqF;AACrF,KAAK,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAE3C,+EAA+E;AAC/E,KAAK,YAAY,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAExF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAElC,qFAAqF;AACrF,KAAK,kBAAkB,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,GAAG,CAAC,GAAG,KAAK;CAC9D,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,QAAQ,EAAE,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACnE,CAAC;AAEF,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM;IAChD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,MAAM;IAC1C;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,IAAI,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA+G7F"}

package/dist/adapter/system-slot.js

@@ -0,0 +1,229 @@
+/**
+ * `createSystemSlot` — THE implementation of the declared-slot façade, the
+ * seam between a STATIC `systems` declaration and a LIVE adapter that only
+ * exists once the world tree is mounted.
+ *
+ * WHY IT EXISTS. An entry declares its systems statically
+ * (`export const systems = { networking: networkingSystem() }`), while the
+ * thing being declared — a joined Colyseus room, a baked navmesh, a mounted
+ * `<Physics>`, a cutscene's camera ownership — is built inside the world tree,
+ * later, and may be replaced (reconnect, remount, hot restart) or go away
+ * (stop). The slot is a stable object the host installs at mount and holds
+ * forever; every call forwards to whatever is attached right now.
+ *
+ * ── THE HONESTY RULE, STATED IN ONE PLACE ───────────────────────────────────
+ * This is why the pattern is centralized: five hand-rolled copies disagreed
+ * about it, and each disagreement was found by a separate review.
+ *
+ *  - An **action** with no live target REFUSES BY NAME
+ *    (`<name>: <unattachedMessage>`). Never a silent no-op — a caller that
+ *    told the game to DO something must learn that it did not happen. An
+ *    action against a live adapter that lacks the member refuses the same
+ *    way, naming the member.
+ *  - A **read** answers its declared HONEST EMPTY — `'disconnected'`, `[]`,
+ *    `null`, `false`. That is not a fabrication: it is the truth of the
+ *    not-attached state, in the same vocabulary the editor's own edit-mode
+ *    adapters use. Reads are also the only kind safe to call from a per-frame
+ *    debug draw, which is why a throw into a rAF loop is never the answer.
+ *  - An **optional** member MIRRORS THE LIVE ADAPTER'S PRESENCE: absent while
+ *    unattached, and absent afterwards when the live adapter itself does not
+ *    provide it. Presence IS the consume-by-presence protocol's signal, so
+ *    the slot may never invent it. Each presence read CAPTURES the adapter it
+ *    saw and forwards to that same instance, so a detach between the read and
+ *    the call answers as the adapter the caller was handed rather than a
+ *    mid-flight swap.
+ *  - A **subscribe** member SURVIVES REATTACHMENT: listeners live on the
+ *    slot, never on the instance, and the slot re-binds its own single
+ *    subscription on every attach/detach. A panel that subscribed once to the
+ *    stable slot object is therefore never left holding a disposed system, and
+ *    it is notified when the live half appears or disappears.
+ *  - A member the config DOES NOT LIST does not exist on the slot at all.
+ *    That is how the anti-shim rule spells omission — e.g. `PhysicsAdapter`'s
+ *    `debugDraw`/`contactPoints` over `@react-three/rapier`, whose debug line
+ *    segments live inside the fiber tree and expose no handle. Absence is a
+ *    capability answer; a stub is a lie.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: whoever built the live adapter (the hook, the bridge component). The
+ * slot owns only the POINTER to it plus its own listener set and its own
+ * subscription to the live half. SHARERS: every reader of the declared
+ * system — editor inspectors, instruments. TEARDOWN: the function `attach`
+ * returns, and nothing else. It is IDENTITY-GUARDED — it clears only while
+ * the same instance is still attached, so a replace-then-teardown-the-old
+ * ordering cannot detach the new one — and detaching never disposes the
+ * adapter, because the slot did not create it.
+ *
+ * WHERE the slot module lives decides how many games share it. A slot in
+ * PROJECT-owned source (the four capability/example façades) is per Play
+ * instance, because the editor stamps mount ids onto project-owned import
+ * specifiers (`server/project-module-instance.ts`) — N instances get N module
+ * graphs and N slots. A slot in an ENGINE module is reached by bare
+ * specifier, which that stamping deliberately never touches, so it is ONE per
+ * page: every Play instance shares it, and concurrent instances' attaches
+ * contend (last attach wins; the loser's detach is dropped by the identity
+ * guard). `rapier-physics-bridge.tsx` is the one such slot today and warns
+ * loudly when contended — prefer project-owned slot modules for anything new.
+ *
+ * NOT A WRAPPER. The slot's members have the adapter interface's own exact
+ * signatures and hand back the implementation's own values; nothing stands
+ * between a caller and the live library object.
+ */
+/**
+ * `absent(reason)` — THE WHOLE-SLOT counterpart of the four per-member policies
+ * above, and the fifth line of the same honesty rule.
+ *
+ * The four policies answer "this slot exists but nothing is attached yet". This
+ * one answers a different question entirely: **this game will never have that
+ * subsystem, and here is what was searched.** A slot simply left out of the
+ * `systems` table cannot say that — an omitted key means "unsupported", which is
+ * the same shape as "nobody looked", and the coverage report has to file it as a
+ * work order forever. Declaring the absence turns an UNANSWERED row into a
+ * terminal one.
+ *
+ * ```ts
+ * export const systems = {
+ *   audio: sfxAudioSystem(),
+ *   physics: rapierPhysicsSystem(),
+ *   networking: absent('single-player: no Colyseus client anywhere in `src/`'),
+ * };
+ * ```
+ *
+ * ## It is a CONSTRUCTOR for the shape that already exists, not a second one
+ *
+ * The returned value IS `VgaiGameSystemEmpty` — the plain
+ * `{ present: false, evidence }` record an INGESTED game declares on
+ * `window.vgaiGame.systems.systemAdapters`, validated by the same single
+ * projection (`ingest/contract-system-adapters.ts`). There is one shape law, not
+ * two: a foreign game cannot import this helper and must stay able to write the
+ * record by hand, so nothing here may brand the runtime value. What the helper
+ * buys a FIRST-PARTY author is the reason-quality check moved to the call site —
+ * our own code failing its own contract fails fast, where an ingested game's
+ * same mistake is filed as a `malformed` verdict for its coverage report.
+ *
+ * ## It is a MARKER, never a stub adapter
+ *
+ * Do not answer an absent slot with an adapter whose methods return zeros. A
+ * `getConnectionState()` of `'disconnected'` on a game with no transport implies
+ * a connection that could exist; that is the fabrication the anti-shim rule
+ * forbids. The absence is STATED, and the host installs nothing for it.
+ *
+ * @param reason What was searched and what was found, in the game's own source
+ *   terms. "no netcode anywhere in `src/`" is a finished answer a reviewer can
+ *   re-run; "not implemented yet" is a plan, and is rejected here.
+ */
+export function absent(reason) {
+    if (typeof reason !== 'string' || reason.trim() === '') {
+        throw new Error('absent(): an absence needs evidence — say what was searched and what was found ' +
+            '(e.g. "no Colyseus client anywhere in `src/`"), so a reviewer can re-run it. ' +
+            'An unevidenced absence asserts something nobody can re-check.');
+    }
+    return { present: false, evidence: reason };
+}
+export function createSystemSlot(config) {
+    const { name, unattachedMessage, members } = config;
+    let live = null;
+    /** Subscribers to the stable slot object; they outlive any one live instance. */
+    const listeners = new Set();
+    /** The slot's own single subscription to whatever is attached. */
+    let liveUnsubscribe = null;
+    let subscribeMember = null;
+    const asRecord = (value) => value;
+    const liveMember = (member) => {
+        if (!live)
+            return undefined;
+        const value = asRecord(live)[member];
+        return typeof value === 'function' ? value : undefined;
+    };
+    const notify = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    const bindLive = () => {
+        liveUnsubscribe?.();
+        liveUnsubscribe = null;
+        if (!live || subscribeMember === null || listeners.size === 0)
+            return;
+        const subscribe = liveMember(subscribeMember);
+        if (!subscribe)
+            return;
+        const result = subscribe.call(live, notify);
+        liveUnsubscribe = typeof result === 'function' ? result : null;
+    };
+    const target = {};
+    const declared = Object.entries(members);
+    for (const [member, spec] of declared) {
+        switch (spec.kind) {
+            case 'action': {
+                // Refuse by name, twice over: no live adapter at all, or a live
+                // adapter that does not carry this member (only ever a foreign
+                // replacement — the blessed implementations carry all of theirs).
+                target[member] = (...args) => {
+                    if (!live)
+                        throw new Error(`${name}: ${unattachedMessage}`);
+                    const fn = liveMember(member);
+                    if (!fn)
+                        throw new Error(`${name}: the live adapter has no ${member}().`);
+                    return fn.apply(live, args);
+                };
+                break;
+            }
+            case 'read': {
+                const { empty } = spec;
+                target[member] = (...args) => {
+                    const current = live;
+                    const fn = liveMember(member);
+                    const value = fn ? fn.apply(current, args) : undefined;
+                    return value ?? empty;
+                };
+                break;
+            }
+            case 'subscribe': {
+                if (subscribeMember !== null) {
+                    throw new Error(`${name}: a slot declares at most one 'subscribe' member (${subscribeMember} and ${member}).`);
+                }
+                subscribeMember = member;
+                target[member] = (listener) => {
+                    listeners.add(listener);
+                    bindLive();
+                    return () => {
+                        listeners.delete(listener);
+                        bindLive();
+                    };
+                };
+                break;
+            }
+            case 'optional': {
+                Object.defineProperty(target, member, {
+                    enumerable: true,
+                    configurable: true,
+                    get() {
+                        const current = live;
+                        const fn = liveMember(member);
+                        if (!fn)
+                            return undefined;
+                        return (...args) => fn.apply(current, args);
+                    },
+                });
+                break;
+            }
+        }
+    }
+    const attach = (next) => {
+        live = next;
+        bindLive();
+        notify();
+        return () => {
+            if (live !== next)
+                return;
+            live = null;
+            bindLive();
+            notify();
+        };
+    };
+    // THE ONE CAST. `exactOptionalPropertyTypes` forbids an optional member
+    // whose getter can yield `undefined`, but that is precisely the honest
+    // shape here — the getter IS how presence mirrors the live adapter — and a
+    // reflectively built object cannot be typed structurally anyway. Callers
+    // see exactly the absent/present behavior the adapter interface documents.
+    return { attach, slot: target };
+}

package/dist/adapter/transform.d.ts

@@ -14,5 +14,15 @@ export interface Transform {
  * needs simulation coordination (`physics`), or is best-effort/inspect-only
  * (`script`/`network`/`external`).
  */
-export type TransformOwner = 'editor' | 'physics' | 'animation' | 'script' | 'network' | 'external';
+/**
+ * Who drives a node's transform right now.
+ *
+ * `'unresolved'` is the answer for a node THIS ADAPTER DOES NOT KNOW, and it is
+ * a distinct answer on purpose: every other member names a driver, so returning
+ * one of them for an unknown id is a positive claim about a node the
+ * implementer has never seen. A game-scoped physics adapter is asked about
+ * every node the editor touches, including nodes belonging to another root —
+ * "not mine" has to be sayable.
+ */
+export type TransformOwner = 'editor' | 'physics' | 'animation' | 'script' | 'network' | 'external' | 'unresolved';
 //# sourceMappingURL=transform.d.ts.map

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

@@ -1 +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"}
+{"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;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,QAAQ,GACR,SAAS,GACT,UAAU,GACV,YAAY,CAAC"}

package/dist/ai/navigation.d.ts

@@ -55,7 +55,23 @@ export declare class NavMeshManager {
     private destroyRecast;
     /** True once a navmesh has been built (for the NavigationAdapter to gate on). */
     hasNavMesh(): boolean;
-    /** Find a straight path between two world positions. Returns [] if no path. */
+    /**
+     * Find a straight path between two world positions.
+     *
+     * THREE OUTCOMES, and only one of them is an empty array:
+     *
+     *  - **No pathfinder.** No navmesh has been built, so there is nothing to
+     *    query. THROWS, the same way {@link createCrowd} does — `[]` here would
+     *    say "I searched and there is no route between these points", which is a
+     *    claim about the level rather than about this manager's state. Callers
+     *    that can be in this position gate on {@link hasNavMesh} first.
+     *  - **The query failed.** recast answered `success: false` WITH an error
+     *    (bad half-extents, no polygon near an endpoint, a status code). THROWS,
+     *    naming recast's own error — a failed search is not a searched-and-empty
+     *    one, and the editor's probe already surfaces this separately from "no
+     *    path found".
+     *  - **Genuinely no route.** The query ran and found nothing. `[]`.
+     */
     findPath(start: Vector3Like, end: Vector3Like): Vector3Like[];
     /** Create a crowd with up to maxAgents agents. */
     createCrowd(maxAgents: number): Crowd;

package/dist/ai/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/ai/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAoD,MAAM,mBAAmB,CAAC;AAC5F,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGzC,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;iEACiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAID,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAA8B;IAE5C,2EAA2E;IAC3E,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO;IA4BrE;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAoBrB,iFAAiF;IACjF,UAAU,IAAI,OAAO;IAIrB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,EAAE;IAO7D,kDAAkD;IAClD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;IAMrC,sDAAsD;IACtD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,cAAc,IAAI,kBAAkB,EAAE;IActC,iGAAiG;IACjG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI;IAShD,sDAAsD;IACtD,UAAU,IAAI,UAAU;IAKxB,6DAA6D;IAC7D,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQpC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAM5B"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/ai/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAoD,MAAM,mBAAmB,CAAC;AAC5F,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGzC,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;iEACiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAID,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAA8B;IAE5C,2EAA2E;IAC3E,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO;IA4BrE;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAoBrB,iFAAiF;IACjF,UAAU,IAAI,OAAO;IAIrB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,EAAE;IAkB7D,kDAAkD;IAClD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;IAMrC,sDAAsD;IACtD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,cAAc,IAAI,kBAAkB,EAAE;IActC,iGAAiG;IACjG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI;IAShD,sDAAsD;IACtD,UAAU,IAAI,UAAU;IAKxB,6DAA6D;IAC7D,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQpC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAM5B"}

package/dist/ai/navigation.js

@@ -79,13 +79,34 @@ export class NavMeshManager {
     hasNavMesh() {
         return this.navMesh !== null;
     }
-    /** Find a straight path between two world positions. Returns [] if no path. */
+    /**
+     * Find a straight path between two world positions.
+     *
+     * THREE OUTCOMES, and only one of them is an empty array:
+     *
+     *  - **No pathfinder.** No navmesh has been built, so there is nothing to
+     *    query. THROWS, the same way {@link createCrowd} does — `[]` here would
+     *    say "I searched and there is no route between these points", which is a
+     *    claim about the level rather than about this manager's state. Callers
+     *    that can be in this position gate on {@link hasNavMesh} first.
+     *  - **The query failed.** recast answered `success: false` WITH an error
+     *    (bad half-extents, no polygon near an endpoint, a status code). THROWS,
+     *    naming recast's own error — a failed search is not a searched-and-empty
+     *    one, and the editor's probe already surfaces this separately from "no
+     *    path found".
+     *  - **Genuinely no route.** The query ran and found nothing. `[]`.
+     */
     findPath(start, end) {
-        if (!this.query)
-            return [];
+        if (!this.query) {
+            throw new Error('NavMeshManager.findPath: no navmesh has been built, so no path can be queried. ' +
+                'Build one first (buildFromMeshes/importNavMesh) — gate on hasNavMesh() if the ' +
+                'caller can run before a bake.');
+        }
         const result = this.query.computePath(start, end);
-        if (!result.success)
-            return [];
+        if (!result.success && result.error) {
+            throw new Error(`NavMeshManager.findPath: recast could not complete the query (${result.error.name}` +
+                `${result.error.status === undefined ? '' : `, status ${result.error.status}`}).`);
+        }
         return result.path;
     }
     /** Create a crowd with up to maxAgents agents. */

package/dist/animation/anim-graph-types.d.ts

@@ -10,16 +10,24 @@
  * the old `.animgraph.json` format) was deleted with the runtime that read
  * them (`anim-graph.ts`).
  */
+/**
+ * The optional fields spell `| undefined` explicitly because the repo compiles
+ * with `exactOptionalPropertyTypes`, and the one producer of these values is
+ * `xstate-animation-meta.ts`'s Zod schema, whose `.optional()` infers
+ * `?: T | undefined`. Without the explicit union the parsed value is not
+ * assignable here and the call site needs a cast — which is exactly what used
+ * to hide field drift between the two declarations (see `asBlendTreeDef`).
+ */
 export interface BlendTreeDef {
     type: '1D' | '2D' | 'direct';
     parameter: string;
-    parameterY?: string;
+    parameterY?: string | undefined;
     children: BlendChild[];
 }
 export interface BlendChild {
     clip: string;
     threshold: number;
-    thresholdY?: number;
-    weight?: number;
+    thresholdY?: number | undefined;
+    weight?: number | undefined;
 }
 //# sourceMappingURL=anim-graph-types.d.ts.map

package/dist/animation/anim-graph-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anim-graph-types.d.ts","sourceRoot":"","sources":["../../src/animation/anim-graph-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"anim-graph-types.d.ts","sourceRoot":"","sources":["../../src/animation/anim-graph-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B"}

package/dist/animation/theatre-clock-binding.d.ts

@@ -74,10 +74,10 @@ export interface TheatreClockBinding {
 /**
  * Subscribe `sequence.position = clock.time` to every crossing of `clock` in
  * the given phase (default `'animation'`). Returns a disposer; call it to
- * stop driving the sequence (e.g. on `GameCleanup.dispose()` or before
- * rebinding on hot reload — this is what keeps HMR from accumulating
- * duplicate listeners, since re-running `setup()` disposes the old binding
- * before creating a new one).
+ * stop driving the sequence (e.g. in the owning component's unmount cleanup,
+ * or before rebinding on hot reload — this is what keeps HMR from
+ * accumulating duplicate listeners: dispose the old binding before creating
+ * a new one).
  *
  * Multiple sheets/sequences can each get their own binding with no shared
  * mutable state on VGAI's side — collision avoidance for the underlying

package/dist/animation/theatre-clock-binding.js

@@ -1,10 +1,10 @@
 /**
  * Subscribe `sequence.position = clock.time` to every crossing of `clock` in
  * the given phase (default `'animation'`). Returns a disposer; call it to
- * stop driving the sequence (e.g. on `GameCleanup.dispose()` or before
- * rebinding on hot reload — this is what keeps HMR from accumulating
- * duplicate listeners, since re-running `setup()` disposes the old binding
- * before creating a new one).
+ * stop driving the sequence (e.g. in the owning component's unmount cleanup,
+ * or before rebinding on hot reload — this is what keeps HMR from
+ * accumulating duplicate listeners: dispose the old binding before creating
+ * a new one).
  *
  * Multiple sheets/sequences can each get their own binding with no shared
  * mutable state on VGAI's side — collision avoidance for the underlying

package/dist/animation/xstate-animation-binding.d.ts.map

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

package/dist/animation/xstate-animation-binding.js

@@ -2,7 +2,7 @@ import * as THREE from 'three';
 import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
 import { evaluateBlendTree } from './blend-node';
 import { attachAnimationRuntimeInspection, } from './runtime-inspection';
-import { clipNamesOf, collectMachineAnimationMeta, isBlendTreeAnimationMeta, } from './xstate-animation-meta';
+import { asBlendTreeDef, clipNamesOf, collectMachineAnimationMeta, isBlendTreeAnimationMeta, } from './xstate-animation-meta';
 /** A binding-time problem such as a missing clip, bone, or ambiguous layer. */
 export class AnimationBindingError extends Error {
     stateId;
@@ -188,7 +188,7 @@ export function bindXStateAnimation(actor, mixer, clips, options = {}) {
     }
     function weightsOf(stateId, meta, context) {
         const weights = isBlendTreeAnimationMeta(meta)
-            ? evaluateBlendTree(meta.blendTree, readParameters(context))
+            ? evaluateBlendTree(asBlendTreeDef(meta.blendTree), readParameters(context))
             : [{ clip: meta.clip, weight: 1 }];
         return weights.map(({ clip, weight }) => ({
             clip,

package/dist/animation/xstate-animation-meta.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { BlendTreeDef } from './anim-graph-types';
 /**
  * E1 — Zod/TypeScript metadata attached to XState state `meta.animation`
  * (spec §11 E1, §5.6, §3.3).
@@ -69,6 +70,18 @@ export declare const AnimationBlendTreeSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     }, z.core.$strict>>;
 }, z.core.$strict>], "type">;
 export type AnimationBlendTree = z.infer<typeof AnimationBlendTreeSchema>;
+/**
+ * The structural-identity claim in this file's header, made COMPILER-CHECKED.
+ *
+ * `evaluateBlendTree` takes `anim-graph-types.ts`'s `BlendTreeDef`, and the
+ * whole reason this schema mirrors that shape field-for-field is so a parsed
+ * value can be handed over with zero conversion. The binding used to spell that
+ * hand-over `as unknown as BlendTreeDef` — a double cast that would have gone on
+ * compiling if either declaration drifted, silently feeding the blend math a
+ * shape it does not describe. This identity function is the assignability
+ * assertion instead: drift here is a type error at the seam that claims it.
+ */
+export declare function asBlendTreeDef(tree: AnimationBlendTree): BlendTreeDef;
 declare const AnimationCrossfadeMetaSchema: z.ZodObject<{
     duration: z.ZodDefault<z.ZodNumber>;
     warp: z.ZodDefault<z.ZodBoolean>;

package/dist/animation/xstate-animation-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xstate-animation-meta.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,QAAA,MAAM,yBAAyB;;;;;kBAcpB,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAwC5E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAInC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM1E,QAAA,MAAM,4BAA4B;;;kBAmBkC,CAAC;AAErE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,QAAA,MAAM,uBAAuB;;;kBAiB0C,CAAC;AAExE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AA2BxE,QAAA,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;kBAiBlB,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,QAAA,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQvB,CAAC;AAEZ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAGnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,IAAI,iBAAiB,CAEvF;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,IAAI,sBAAsB,CAEjG;AAMD,iFAAiF;AACjF,qBAAa,4BAA6B,SAAQ,KAAK;IAGnD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;gBAF7B,OAAO,EAAE,MAAM,EACN,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAKhC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAazF;AAMD,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,0BAA0B,GAC/B,yBAAyB,EAAE,CAU7B;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAE9D"}
+{"version":3,"file":"xstate-animation-meta.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-meta.ts"],"names":[],"mappings":"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"}