@moku-labs/game 0.0.1 → 0.0.2

package/dist/types-CTPS9GBu.d.mts

@@ -0,0 +1,742 @@
+import { L as Json, k as Api, lt as Require, t as Api$1, w as TypeTag } from "./types-JNc_UQBo.mjs";
+import { D as AnyComponent, N as Entity, T as TrackSegment, b as MotionHandle, g as Ease, k as AnyComponentValue, u as Api$2, w as TrackOptions } from "./types-BxkNNYul.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/plugins/anim/tween/types.d.ts
+/**
+ * One running track: the numeric fields of one component of one entity moving from the values
+ * read at the end of the delay to the exact target, straight or through keyframe segments. A
+ * track with repeats walks again from its first segment each time a run ends.
+ *
+ * @example
+ * ```ts
+ * const track: Track = {
+ *   id: 1, entity: 1_048_576, component: Transform, to: { x: 200 },
+ *   keys: { x: "1048576:Transform:x" }, ms: 350, ease: "out", delayMs: 0, elapsed: 0,
+ *   from: undefined, muted: () => new Set(), additive: false, driven: false, bornFrame: 4,
+ *   ended: false, segments: undefined, repeatsLeft: 0, held: false
+ * };
+ * ```
+ */
+type Track = {
+  readonly id: number;
+  readonly entity: Entity;
+  readonly component: AnyComponent; /** The target fields. Retarget deletes the fields a newer absolute track took over. */
+  to: Record<string, number>;
+  /**
+   * The key of the owner, bases and offsets tables per field, built once when the track starts.
+   * It keeps a field `to` lost, which nothing reads again.
+   */
+  readonly keys: Readonly<Record<string, string>>;
+  readonly ms: number;
+  readonly ease: Ease;
+  readonly delayMs: number;
+  elapsed: number; /** Read when the delay ends, never earlier. */
+  from: Record<string, number> | undefined;
+  readonly muted: () => ReadonlySet<string>;
+  readonly additive: boolean; /** True for a track a timeline step advances by hand; the frame step leaves it alone. */
+  readonly driven: boolean; /** The frame step the track was born in. That step does not advance it a second time. */
+  readonly bornFrame: number;
+  ended: boolean;
+  /**
+   * The keyframe segments the track walks over `ms`, or `undefined` for a straight track. A
+   * segment without an ease runs on the track's `ease`.
+   */
+  readonly segments: readonly TrackSegment[] | undefined;
+  /**
+   * The runs still to go after the one that plays: `0` for a track that runs once, `Infinity`
+   * for a loop (`repeat: "forever"`), which never ends by itself.
+   */
+  repeatsLeft: number;
+  /**
+   * True while a loop stands on its first key and has written it: the hold writes once, and the
+   * walk clears it, so the next hold writes the first key again.
+   */
+  held: boolean;
+};
+/**
+ * A motion handle that can also be advanced by hand: what the timeline cursor needs, so a track
+ * born inside a frame step still consumes the remainder of that step's delta.
+ *
+ * @example
+ * ```ts
+ * const motion: StepMotion = { ...inert, advance: () => 0 };
+ * motion.advance(16); // 0: nothing is left over
+ * ```
+ */
+type StepMotion = MotionHandle & {
+  /**
+   * Advances the track by one delta.
+   *
+   * @param deltaMs - Milliseconds of game time to consume.
+   * @returns The milliseconds left over past the end of the track.
+   */
+  advance(deltaMs: number): number;
+};
+//#endregion
+//#region src/plugins/anim/timeline/types.d.ts
+/**
+ * A sound, owned by `anim` and handled by `audio`. It is a `flow` descriptor and a timeline step
+ * at once: `fx(sfx("board.merge"))` in a node, or `sfx("board.merge")` inside a `sequence`.
+ *
+ * @example
+ * ```ts
+ * const descriptor: SfxDescriptor = {
+ *   kind: "sfx", payload: { key: "board.merge", bus: "sfx" }, cosmetic: true
+ * };
+ * ```
+ */
+type SfxDescriptor = {
+  readonly kind: "sfx";
+  readonly payload: {
+    readonly key: string;
+    readonly bus: string;
+  };
+  readonly cosmetic: true;
+};
+/**
+ * A haptic tick, owned by `anim` and handled by `platform`. Like `sfx` it is a descriptor and a
+ * timeline step at once.
+ *
+ * @example
+ * ```ts
+ * const descriptor: HapticDescriptor = {
+ *   kind: "haptic", payload: { kind: "light" }, cosmetic: true
+ * };
+ * ```
+ */
+type HapticDescriptor = {
+  readonly kind: "haptic";
+  readonly payload: {
+    readonly kind: string;
+  };
+  readonly cosmetic: true;
+};
+/**
+ * The two descriptors `anim` owns. As a step, the descriptor is dispatched through
+ * `flow.fx.dispatch` when the step is reached; a kind nobody handles is silent.
+ *
+ * @example
+ * ```ts
+ * const step: FxStep = { kind: "haptic", payload: { kind: "light" }, cosmetic: true };
+ * ```
+ */
+type FxStep = SfxDescriptor | HapticDescriptor;
+/**
+ * The descriptor `play(animation, slots)` builds. The payload names the animation, so the
+ * handler resolves the definition from the registry instead of carrying a function.
+ *
+ * @example
+ * ```ts
+ * const descriptor: PlayDescriptor = {
+ *   kind: "play",
+ *   payload: { animation: "hud.coinsFly", slots: { from: { projection: "hud", key: "coins" } } },
+ *   cosmetic: true
+ * };
+ * ```
+ */
+type PlayDescriptor = {
+  readonly kind: "play";
+  readonly payload: {
+    readonly animation: string;
+    readonly slots: Json;
+  };
+  readonly cosmetic: true;
+};
+/**
+ * One step of a choreography: plain frozen data with no callback inside, so a step tree can be
+ * read, logged and compared. A `spawn` step carries the component values of a temporary entity,
+ * made when the step is reached and despawned when the timeline ends.
+ *
+ * @example
+ * ```ts
+ * const step: Step = { kind: "wait", ms: 120 };
+ * ```
+ */
+type Step = {
+  readonly kind: "sequence";
+  readonly steps: readonly Step[];
+} | {
+  readonly kind: "parallel";
+  readonly steps: readonly Step[];
+} | {
+  readonly kind: "wait";
+  readonly ms: number;
+} | {
+  readonly kind: "mark";
+  readonly name: string;
+} | {
+  readonly kind: "tween";
+  readonly target: Target;
+  readonly component: AnyComponent;
+  readonly to: Readonly<Record<string, number>>;
+  readonly ms: number;
+  readonly ease: Ease;
+  readonly delayMs: number;
+  readonly additive: boolean; /** `"root"`: the `Transform` fields are a root pose, turned local when the track starts. */
+  readonly space: "local" | "root";
+} | {
+  readonly kind: "set";
+  readonly target: Target;
+  readonly component: AnyComponent;
+  readonly patch: Readonly<Record<string, unknown>>;
+} | {
+  readonly kind: "frames";
+  readonly target: Target;
+  readonly keys: readonly string[];
+  readonly fps: number;
+  readonly loop: boolean;
+} | {
+  readonly kind: "spawn";
+  readonly id: string;
+  readonly components: readonly AnyComponentValue[];
+  readonly layer: string;
+  readonly order: number;
+} | FxStep | {
+  readonly kind: "use";
+  readonly id: string;
+  readonly step: Step;
+};
+/**
+ * Reserved for Spine and the other external players: `external` throws, and this is the shape it
+ * would take. Exported as a type only.
+ *
+ * @example
+ * ```ts
+ * const player: ExternalPlayer = { name: "spine", play: () => undefined };
+ * ```
+ */
+type ExternalPlayer = {
+  readonly name: string;
+  play(clip: string): unknown;
+};
+/**
+ * Where one step of a running timeline stands. One mutable record per step of the tree, built
+ * when the timeline starts.
+ *
+ * @example
+ * ```ts
+ * const cursor: Cursor = {
+ *   step: { kind: "wait", ms: 120 }, children: [], index: 0, elapsed: 0,
+ *   motion: undefined, started: false, ended: false
+ * };
+ * ```
+ */
+type Cursor = {
+  readonly step: Step;
+  readonly children: readonly Cursor[]; /** Position in a `sequence`, and the last written key of a `frames` step. */
+  index: number; /** Consumed milliseconds of a `wait` or a `frames` step. */
+  elapsed: number;
+  motion: StepMotion | undefined;
+  started: boolean;
+  ended: boolean;
+};
+/**
+ * What the cursor reaches the rest of the engine through. Injected, so `timeline` never imports
+ * the run-time code of `tween` or of another plugin.
+ */
+type TimelineRuntime = {
+  /**
+   * Resolves a target to an entity.
+   *
+   * @param target - The projection key, the entity or the spawned id a step names.
+   * @param spawned - The spawn table of the timeline that asks; a spawned id resolves only there.
+   * @returns The entity, or `undefined` when no live view, element or spawned entity holds it.
+   */
+  entityOf(target: Target, spawned?: ReadonlyMap<string, Entity>): Entity | undefined;
+  /**
+   * Spawns a temporary entity owned by `anim`. The timeline that spawned it despawns it when it
+   * ends, whichever way it ends.
+   *
+   * @param components - The component values the entity starts with, `Layer` and `Order` included.
+   * @returns The new entity.
+   */
+  spawn(components: readonly AnyComponentValue[]): Entity;
+  /**
+   * Reads a component of an entity, which is also the liveness check of a step.
+   *
+   * @param entity - The entity to read.
+   * @param component - The component to read.
+   * @returns The stored value, or `undefined`.
+   */
+  read(entity: Entity, component: AnyComponent): Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Writes a patch through `ecs.set`, so `changed()` sees it.
+   *
+   * @param entity - The entity to write.
+   * @param component - The component to write.
+   * @param patch - The fields to overwrite.
+   */
+  write(entity: Entity, component: AnyComponent, patch: Record<string, unknown>): void;
+  /**
+   * Turns the root-space target of a `tween` step into the local target under the entity's
+   * parent, through `localPoseOf` of `renderer`.
+   *
+   * @param entity - The entity the step moves.
+   * @param component - The component the step drives; only `Transform` is converted.
+   * @param to - The numeric target fields, in root space.
+   * @returns The target fields in the space of the entity's parent.
+   */
+  toLocal(entity: Entity, component: AnyComponent, to: Readonly<Record<string, number>>): Record<string, number>;
+  /**
+   * Starts one track on the tween core.
+   *
+   * @param entity - The entity to animate.
+   * @param component - The component to animate.
+   * @param to - The numeric target fields.
+   * @param options - Duration, easing, delay and the additive flag.
+   * @returns The motion of the track, advanceable by hand.
+   */
+  start(entity: Entity, component: AnyComponent, to: Record<string, number>, options: TrackOptions): StepMotion;
+  /**
+   * Hands a descriptor step to `flow.fx.dispatch`.
+   *
+   * @param descriptor - The `sfx` or `haptic` step that was reached.
+   */
+  dispatch(descriptor: FxStep): void;
+  /**
+   * Reports a mark: the event, the `onMark` listeners and the timeline's own list.
+   *
+   * @param animation - Id of the animation the mark belongs to.
+   * @param name - Name of the mark.
+   */
+  mark(animation: string, name: string): void;
+  /**
+   * Lifts the idle frame rate, because something started to move.
+   */
+  wake(): void;
+};
+/**
+ * One running timeline: its cursor, the marks it reached, the entities it counts on, the entities
+ * it spawned and despawns at its end, and the resolver of its `done` promise.
+ */
+type RunningTimeline = {
+  readonly id: number;
+  readonly animation: string;
+  readonly cursor: Cursor;
+  readonly marks: string[];
+  readonly entities: readonly Entity[]; /** The entities its `spawn` steps made, by spawn id. Despawned when the timeline ends. */
+  readonly spawned: Map<string, Entity>;
+  readonly resolve: () => void;
+  ended: boolean;
+};
+declare namespace types_d_exports {
+  export { AnimApi, AnimCtx, AnimationDefinition, AnimationSpec, AnyAnimationDefinition, BuildTools, Config, Cursor, Deps, Events, ExternalPlayer, FxStep, HapticDescriptor, KernelSlice, MarkListener, MotionKeyframe, PlayDescriptor, PlayHandle, Pose, RunningTimeline, SfxDescriptor, SlotRecord, SlotTags, SlotValue, SlotValues, State, Step, StepMotion, Target, TimelineRuntime, Track };
+}
+/**
+ * What a step and a slot are pointed at: the projection key of a live view or of an element a
+ * plugin above registered with `registerKey`, an entity, or the id of an entity a `spawn` step of
+ * the same timeline made (`spawned(id)`). A node passes keys, never entities.
+ *
+ * @example
+ * ```ts
+ * const counter: Target = { projection: "hud", key: "coins" };
+ * const flyingCoin: Target = spawned("coin1"); // { spawned: "coin1" }
+ * ```
+ */
+type Target = {
+  projection: string;
+  key: string;
+} | Entity | {
+  spawned: string;
+};
+/**
+ * The pose `at(target)` answers with: where the target rests in root (reference) space, its rest
+ * `Transform` composed through the `Parent` chain, or the identity pose when nothing is there.
+ *
+ * @example
+ * ```ts
+ * const pose: Pose = { x: 540, y: 960, rotation: 0, scale: 1 };
+ * ```
+ */
+type Pose = {
+  x: number;
+  y: number;
+  rotation: number;
+  scale: number;
+};
+/**
+ * The slot declaration of an animation: one type tag per slot, each carrying one target or a
+ * list of targets.
+ *
+ * @example
+ * ```ts
+ * const slots: SlotTags = { items: type<Target[]>(), card: type<Target>() };
+ * ```
+ */
+type SlotTags = Readonly<Record<string, TypeTag<Target> | TypeTag<Target[]>>>;
+/**
+ * The targets `play` and `use` take, read off the slot tags of the animation.
+ *
+ * @example
+ * ```ts
+ * type Slots = SlotValues<{ card: TypeTag<Target> }>; // { card: Target }
+ * ```
+ */
+type SlotValues<Tags extends SlotTags> = { [Name in keyof Tags]: SlotValue<Tags[Name]> };
+/**
+ * What one slot tag stands for: a list of targets when the tag declared one, a single target
+ * otherwise. Distributive on purpose, so the erased `SlotTags` widens to both.
+ *
+ * @example
+ * ```ts
+ * type One = SlotValue<TypeTag<Target>>; // Target
+ * ```
+ */
+type SlotValue<Tag> = Tag extends TypeTag<Target[]> ? Target[] : Target;
+/**
+ * The slots of a running animation with their tags erased, as `build` and the `play` handler
+ * read them.
+ *
+ * @example
+ * ```ts
+ * const slots: SlotRecord = { card: { projection: "hud", key: "order" } };
+ * ```
+ */
+type SlotRecord = SlotValues<SlotTags>;
+/**
+ * What `build` is handed next to the slots: `at` reads where a target rests at play time, in root
+ * space (its rest `Transform` composed through the `Parent` chain, every pivot applied), so a
+ * choreography can fly one element to where another one rests, even inside a scaled slot. A view
+ * that has a `Parent` itself is aimed at that pose with a `tween` in `space: "root"`.
+ *
+ * @example
+ * ```ts
+ * const tools: BuildTools = { at: () => ({ x: 0, y: 0, rotation: 0, scale: 1 }) };
+ * ```
+ */
+type BuildTools = {
+  at(target: Target): Pose;
+};
+/**
+ * One animation: an id, the slots it takes and the pure function that builds its step tree. The
+ * same definition may play twice at once, because `build` runs per play.
+ *
+ * @example
+ * ```ts
+ * const coinsFly: AnimationDefinition<{ from: TypeTag<Target> }> = defineAnimation("hud.coinsFly", {
+ *   slots: { from: type<Target>() },
+ *   build: ({ from }) => tween(from, Transform, { scale: 0.4 }, { ms: 600 })
+ * });
+ * coinsFly.id; // "hud.coinsFly"
+ * ```
+ */
+type AnimationDefinition<Tags extends SlotTags = SlotTags> = {
+  readonly id: string;
+  readonly slots: Tags;
+  build(slots: SlotValues<Tags>, tools: BuildTools): Step;
+};
+/**
+ * What `defineAnimation` is given: the slots the animation takes and the pure function that
+ * builds its step tree.
+ *
+ * @example
+ * ```ts
+ * const spec: AnimationSpec<{ card: TypeTag<Target> }> = {
+ *   slots: { card: type<Target>() },
+ *   build: ({ card }) => tween(card, Transform, { scale: 1.2 }, { ms: 120 })
+ * };
+ * ```
+ */
+type AnimationSpec<Tags extends SlotTags> = {
+  readonly slots: Tags;
+  build(slots: SlotValues<Tags>, tools: BuildTools): Step;
+};
+/**
+ * An animation with its slot tags erased, as the registry stores it.
+ *
+ * @example
+ * ```ts
+ * const stored: AnyAnimationDefinition = { id: "hud.coinsFly", slots: {}, build: () => wait(0) };
+ * ```
+ */
+type AnyAnimationDefinition = AnimationDefinition<SlotTags>;
+/**
+ * What `play` hands back: the motion contract over the whole step tree, the promise of its end
+ * and the marks it reached so far.
+ *
+ * @example
+ * ```ts
+ * const handle: PlayHandle = app.anim.play(coinsFly, { from: { projection: "hud", key: "coins" } });
+ * handle.marks(); // []: nothing reached yet
+ * ```
+ */
+type PlayHandle = MotionHandle & {
+  readonly done: Promise<void>;
+  marks(): readonly string[];
+};
+/**
+ * A listener of `onMark`: the animation id and the name of the mark that was reached.
+ *
+ * @example
+ * ```ts
+ * const reached: string[] = [];
+ * const listener: MarkListener = (_animation, mark) => reached.push(mark);
+ * ```
+ */
+type MarkListener = (animation: string, mark: string) => void;
+/**
+ * anim plugin events.
+ *
+ * @example
+ * ```ts
+ * // A feature plugin waits for the mark its choreography emits.
+ * createPlugin("rewardLog", {
+ *   depends: [animPlugin],
+ *   hooks: ctx => ({ "anim:mark": ({ mark }) => ctx.log.info("mark", { mark }) })
+ * }); // the `done` mark of orders.deliver logs { mark: "done" }
+ * ```
+ */
+type Events = {
+  /** A `mark` step was reached, or jumped by `finish()`. */"anim:mark": {
+    animation: string;
+    mark: string;
+  }; /** A timeline ended or was finished. Not emitted on `cancel()`. */
+  "anim:finished": {
+    animation: string;
+  };
+};
+/**
+ * One key of a keyframe track in `defineMotion`: where on the track it sits (`at`, 0..1 of
+ * `transition.ms`), the curve of the segment that ends on it (default `"inOut"`) and the pose.
+ * `dx` and `dy` are offsets from the rest pose in reference units; `rotation` (radians), `scale`
+ * and `alpha` are absolute. A field the key leaves out holds the previous key's value.
+ *
+ * An enter walk starts on the first key and ends on the rest pose at `at: 1`; an exit walk starts
+ * where the view is and ends on the last key, the pose the element leaves in.
+ *
+ * In a loop (`loop: { track }`) every Transform field is an offset added to the rest pose: `dx`, `dy`, `rotation`
+ * and `scale` (`scale: 0.05` grows a scale-1 view to 1.05). `alpha` stays absolute. The loop
+ * stands on its first key until that key's `at`, and its last key repeats its first one.
+ *
+ * @example
+ * ```ts
+ * // A popup board at 42 % of its swing: 14 u below its rest, tilted 5°, slightly larger.
+ * const key: MotionKeyframe = { at: 0.42, ease: "out", Transform: { dy: 14, rotation: 0.087, scale: 1.04 } };
+ * ```
+ */
+type MotionKeyframe = {
+  readonly at: number;
+  readonly ease?: Ease;
+  readonly Transform?: {
+    readonly dx?: number;
+    readonly dy?: number;
+    readonly rotation?: number;
+    readonly scale?: number;
+  };
+  readonly Shape?: {
+    readonly alpha?: number;
+  };
+  readonly Sprite?: {
+    readonly alpha?: number;
+  };
+  readonly NineSlice?: {
+    readonly alpha?: number;
+  };
+};
+/**
+ * anim plugin config. The timings live in the steps and in `defineMotion`, not here: a
+ * choreography that reads its duration from a config cannot be read as text.
+ *
+ * @example
+ * ```ts
+ * createApp({ plugins: [...screen], pluginConfigs: { anim: { maxTracks: 500, reducedMotion: true } } });
+ * ```
+ */
+type Config = {
+  /** Dev guard: one warning each time the running track count rises past this number. */maxTracks: number;
+  /**
+   * Start value of reduced motion: every track but a loop takes 0 ms and every loop stands on
+   * its first key. `app.anim.setReducedMotion(on)` switches it while the game runs.
+   */
+  reducedMotion: boolean;
+};
+/**
+ * anim plugin state: the one track table, the field bookkeeping of the retarget policy and the
+ * offsets accumulator, the running timelines and the animation registry.
+ */
+type State = {
+  /** The one track table. Insertion order is advance order. */tracks: Map<number, Track>; /** Ids of tracks and timelines. */
+  nextId: number; /** `"<entity>:<component>:<field>"` to the id of the absolute track that drives the field. */
+  owner: Map<string, number>; /** Per field key, the delta each additive track contributes. */
+  offsets: Map<string, Map<number, number>>; /** Per field key, the value the offsets are added to. Dropped when no track drives the field. */
+  bases: Map<string, number>; /** The running timelines, by id. */
+  timelines: Map<number, RunningTimeline>; /** The `animations` of every feature, read in `onStart`. */
+  registry: Map<string, AnyAnimationDefinition>; /** `onMark` subscribers, in subscription order. */
+  markListeners: Set<MarkListener>; /** Counter of the frame steps. A track born in the running step is not advanced by it. */
+  frame: number; /** True while the track count is over `maxTracks`, so the warning is one per crossing. */
+  overMaxTracks: boolean; /** The live reduced-motion switch. The frozen `Config.reducedMotion` only seeds it. */
+  reducedMotion: boolean; /** Remover of `world.projection.setDriver`. */
+  removeDriver: (() => void) | undefined; /** Remover of `time.onFrame("animate")`. */
+  offFrame: (() => void) | undefined; /** Remover of `flow.fx.handle("play")`. */
+  offPlay: (() => void) | undefined; /** Bound in `onInit`, so the teardown context can end everything with the state alone. */
+  finishAll: (() => void) | undefined;
+};
+/**
+ * anim plugin API, `app.anim`: play a choreography, end everything, count what runs and listen
+ * to the marks. A choreography may spawn temporary entities; they live exactly as long as its
+ * timeline.
+ *
+ * @example
+ * ```ts
+ * // The board is full: a toast sign drops in, holds for 1.6 s and leaves. Nothing stays behind.
+ * const toastBoardFull = defineAnimation("board.toastBoardFull", {
+ *   slots: {},
+ *   build: () =>
+ *     sequence(
+ *       spawn("sign", [Text({ content: "Board is full", style: "title" }), Transform({ x: 540, y: -120 })]),
+ *       tween(spawned("sign"), Transform, { y: 300 }, { ms: 400, ease: "outBack" }),
+ *       wait(1600),
+ *       tween(spawned("sign"), Transform, { y: -120 }, { ms: 300, ease: "in" })
+ *     )
+ * });
+ * const handle = app.anim.play(toastBoardFull, {});
+ *
+ * for (let frame = 0; frame < 150; frame += 1) app.time.step(16);
+ * handle.active(); // false: the timeline ended and despawned the sign
+ * ```
+ */
+type AnimApi = {
+  /**
+   * Builds the step tree of an animation with the given targets and starts it. The tree runs
+   * from the next frame step on, in game time, so `time.setScale` and a pause apply to it. `at`
+   * inside `build` answers where a target rests in root space, even inside a scaled slot. A
+   * `tween` with `space: "root"` lands a hosted view on such a pose: a board item inside the board
+   * slot flies onto an order card of the HUD.
+   *
+   * @param animation - What `defineAnimation` returned.
+   * @param slots - One target, or a list of targets, per declared slot.
+   * @returns The handle of the running timeline.
+   * @throws {Error} When the tree spawns one id twice.
+   * @example
+   * ```ts
+   * // The reward is claimed: a coin appears on the reward picture and flies to the HUD counter.
+   * const coinsFly = defineAnimation("hud.coinsFly", {
+   *   slots: { from: type<Target>(), to: type<Target>() },
+   *   build: ({ from, to }, { at }) =>
+   *     sequence(
+   *       spawn("coin1", [
+   *         Sprite({ texture: "ui.icon-coin", width: 64, height: 64, fit: "contain" }),
+   *         Transform({ x: at(from).x, y: at(from).y })
+   *       ], { order: 50 }),
+   *       tween(spawned("coin1"), Transform, { x: at(to).x, y: at(to).y }, { ms: 600, ease: "inCubic" }),
+   *       mark("landed")
+   *     )
+   * });
+   * const handle = app.anim.play(coinsFly, {
+   *   from: { projection: "reward", key: "picture" },
+   *   to: { projection: "hud", key: "coins" }
+   * });
+   *
+   * for (let frame = 0; frame < 40; frame += 1) app.time.step(16);
+   * handle.marks(); // ["landed"]: the coin reached the counter and was despawned
+   * ```
+   */
+  play<Tags extends SlotTags>(animation: AnimationDefinition<Tags>, slots: SlotValues<Tags>): PlayHandle;
+  /**
+   * Ends every track and every timeline now: each writes its exact target, the marks of a
+   * running timeline are jumped in tree order, every entity a timeline spawned is despawned and
+   * every pending `done` resolves.
+   *
+   * @example
+   * ```ts
+   * // A /control tool skips the board-full toast mid-flight: the sign is gone at once.
+   * app.anim.play(toastBoardFull, {});
+   * app.time.step(16);
+   *
+   * app.anim.finishAll();
+   * app.anim.active(); // 0
+   * ```
+   */
+  finishAll(): void;
+  /**
+   * How many tracks are in the table, the delayed ones and the running loops included. A loop
+   * never ends by itself, so a screen at rest counts one track per loop lane it shows.
+   *
+   * @returns The number of running tracks.
+   * @example
+   * ```ts
+   * // The assertion every motion test ends with: the screen came to rest.
+   * app.anim.active(); // 0
+   *
+   * // Two order cards sway on their pins (a `loop` of rotation keys): at rest, two loops run.
+   * app.anim.active(); // 2
+   * ```
+   */
+  active(): number;
+  /**
+   * Whether reduced motion is on. It starts at `Config.reducedMotion` and `setReducedMotion`
+   * switches it.
+   *
+   * @returns True while every new track takes 0 ms and every loop stands on its first key.
+   * @example
+   * ```ts
+   * // A settings popup shows the switch as the player left it.
+   * app.anim.reducedMotion(); // false: the start value of Config.reducedMotion
+   * ```
+   */
+  reducedMotion(): boolean;
+  /**
+   * Switches reduced motion. While it is on, every track started from then on takes 0 ms: enter
+   * and exit, state changes, change and settle motions, drag returns and timeline tweens land on
+   * their target at the next frame, and their marks and sounds still fire. Every loop stands on
+   * its first key, a running one at once. Tracks already running keep their length.
+   *
+   * @param on - True for less motion, false for the full motion.
+   * @example
+   * ```ts
+   * // The player turns on "Less motion" in the settings popup.
+   * app.anim.setReducedMotion(true);
+   * app.anim.reducedMotion(); // true: a popup opened now stands in its rest pose next frame
+   * ```
+   */
+  setReducedMotion(on: boolean): void;
+  /**
+   * Registers a listener called for every mark a timeline reaches, next to the `anim:mark`
+   * event. A listener that throws is logged and the listeners after it still run.
+   *
+   * @param fn - Called with the animation id and the mark name.
+   * @returns The remover; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // A test waits for the "done" mark of the delivery instead of counting frames.
+   * const reached: string[] = [];
+   * const off = app.anim.onMark((animation, mark) => reached.push(`${animation}:${mark}`));
+   *
+   * off(); // reached: ["orders.deliver:done"]
+   * ```
+   */
+  onMark(fn: MarkListener): () => void;
+};
+/**
+ * Resolved dependency APIs. `renderer` is not among them: `anim` writes its `Sprite` and reads
+ * its `Transform` through the component objects, which are plain data, composes the root pose
+ * of `at` with the pure `rootPoseOf` of `renderer/sync/pose.ts`, and turns the target of a
+ * `tween` in `space: "root"` local with the pure `localPoseOf` of the same module.
+ */
+type Deps = {
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `index.ts` writes `events` with an annotated `register` (core spec `14-EVENT-REGISTRATION.md`
+ * row 8), so the own events reach the context the kernel hands the factories and `emit` is the
+ * kernel's own, anim-typed one. No member of the context is cast.
+ */
+type KernelSlice = PluginCtx<Config, State, Events> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context of the anim plugin: the kernel slice and the three resolved dependencies.
+ */
+type AnimCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+//#endregion
+export { Config as a, SlotValues as c, types_d_exports as d, ExternalPlayer as f, Step as g, SfxDescriptor as h, BuildTools as i, State as l, PlayDescriptor as m, AnimationDefinition as n, MotionKeyframe as o, HapticDescriptor as p, AnimationSpec as r, SlotTags as s, AnimApi as t, Target as u };