@moku-labs/game 0.0.1 → 0.0.2

package/dist/types-BxkNNYul.d.mts

@@ -0,0 +1,2840 @@
+import { D as Hint, I as Events$2, K as Snapshot, L as Json, M as Time, P as Api$3, R as Root, X as Api$5, k as Api$2, lt as Require, nt as Api$6, st as Config$2, t as Api$4 } from "./types-JNc_UQBo.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/plugins/world/ecs/types.d.ts
+/**
+ * Entity id: `generation * 2 ** 20 + index`, a safe integer. A freed index comes back with a
+ * higher generation, so an id is never silently reused.
+ *
+ * @example
+ * ```ts
+ * const entity: Entity = 1_048_576; // generation 1, index 0
+ * ```
+ */
+type Entity = number;
+/**
+ * Who owns an entity. Every `spawn` names one, so `despawnOwnedBy` can free exactly one owner's
+ * entities and `snapshot()` can say where an entity came from.
+ *
+ * @example
+ * ```ts
+ * const owner: Owner = { kind: "projection", name: "board.items" };
+ * ```
+ */
+type Owner = {
+  kind: "projection" | "node" | "plugin";
+  name: string;
+};
+/**
+ * One entity as `snapshot()` reads it: its id and the two halves of the id, its owner, every
+ * component value that is plain JSON, and the names of the ones that are not.
+ *
+ * @example
+ * ```ts
+ * const entity: EntitySnapshot = {
+ *   id: 1_048_576, index: 0, generation: 1, owner: { kind: "projection", name: "board.items" },
+ *   components: { Layer: { name: "items" } }, skipped: ["Display"]
+ * };
+ * ```
+ */
+type EntitySnapshot = {
+  id: Entity;
+  index: number;
+  generation: number;
+  owner: Owner;
+  components: Record<string, Json>;
+  skipped: string[];
+};
+/**
+ * The whole world as plain JSON: the effective mode, every entity sorted by index and every
+ * resource that is JSON.
+ *
+ * @example
+ * ```ts
+ * const empty: WorldSnapshot = { mode: "live", entities: [], resources: {} };
+ * ```
+ */
+type WorldSnapshot = {
+  mode: WorldMode;
+  entities: EntitySnapshot[];
+  resources: Record<string, Json>;
+};
+/**
+ * The four phases systems run in, in frame order.
+ *
+ * @example
+ * ```ts
+ * const phase: WorldPhase = "animate";
+ * ```
+ */
+type WorldPhase = "input" | "animate" | "layout" | "sync";
+/**
+ * World mode. `"paused"` and `"fast"` skip the phases `input`, `animate` and `layout`; phase
+ * `sync` runs in every mode.
+ *
+ * @example
+ * ```ts
+ * const mode: WorldMode = "fast";
+ * ```
+ */
+type WorldMode = "live" | "paused" | "fast";
+/**
+ * One component value ready to be written: the storage key and the frozen data.
+ *
+ * @example
+ * ```ts
+ * const value: ComponentValue<{ level: number }> = { type: Item, value: { level: 2 } };
+ * ```
+ */
+type ComponentValue<Value extends object> = {
+  readonly type: ComponentType<Value>;
+  readonly value: Readonly<Value>;
+};
+/**
+ * A tag value. A tag carries no data and is stored as `true`.
+ *
+ * @example
+ * ```ts
+ * const held: TagValue = { type: Held, value: true };
+ * ```
+ */
+type TagValue = {
+  readonly type: TagType;
+  readonly value: true;
+};
+/**
+ * Any component or tag value, as `spawn` and `view` return them.
+ *
+ * @example
+ * ```ts
+ * const values: AnyComponentValue[] = [Held()];
+ * ```
+ */
+type AnyComponentValue = {
+  readonly type: AnyComponentType;
+  readonly value: object | true;
+};
+/**
+ * A component type whose value shape is erased to a plain record: what the projection writes when
+ * it only knows the component by name.
+ *
+ * @example
+ * ```ts
+ * const erased: AnyComponent = component("Transform", { x: 0, y: 0 }) as AnyComponent;
+ * erased.componentName; // "Transform"
+ * ```
+ */
+type AnyComponent = ComponentType<Record<string, unknown>>;
+/**
+ * A component type made by `component()`: callable to build a value, and carrying the storage
+ * name plus the defaults that give the TypeScript type, the JSON shape and the inspector schema.
+ *
+ * @example
+ * ```ts
+ * const Item: ComponentType<{ kind: string; level: number }> = component("Item", {
+ *   kind: "",
+ *   level: 1
+ * });
+ * Item({ level: 2 }); // { type: Item, value: { kind: "", level: 2 } }
+ * Item.owned; // []: a projection view writes every field
+ * ```
+ */
+type ComponentType<Value extends object> = {
+  (patch?: Partial<Value>): ComponentValue<Value>;
+  readonly componentName: string;
+  readonly defaults: Readonly<Value>;
+  readonly kind: "component"; /** Fields a plugin writes and a projection view never does, so a view never corrects them. */
+  readonly owned: readonly string[];
+};
+/**
+ * A tag type made by `tag()`: a component with no data.
+ *
+ * @example
+ * ```ts
+ * const Held: TagType = tag("Held");
+ * Held(); // { type: Held, value: true }
+ * ```
+ */
+type TagType = {
+  (): TagValue;
+  readonly componentName: string;
+  readonly kind: "tag";
+};
+/**
+ * What the world stores about a component or tag type, independent of its data type.
+ *
+ * @example
+ * ```ts
+ * const registered: AnyComponentType = { componentName: "Held", kind: "tag" };
+ * ```
+ */
+type AnyComponentType = {
+  readonly componentName: string;
+  readonly kind: "component" | "tag";
+};
+/**
+ * What the ECS needs from a component type to read and write its store: the name and the
+ * defaults, never the call signature. A component bound to a game's keys by a `…For` binder
+ * (`Narrowed`) is the same object with a narrower call, so it passes here unchanged.
+ *
+ * @example
+ * ```ts
+ * const ref: ComponentHandle<{ x: number }> = component("Pos", { x: 0 });
+ * ref.defaults; // { x: 0 }
+ * ```
+ */
+type ComponentHandle<Value extends object> = {
+  readonly componentName: string;
+  readonly defaults: Readonly<Value>;
+  readonly kind: "component";
+};
+/**
+ * A component type whose call signature takes a narrower patch: the same object, the same
+ * store, the compiler refuses what the game's generated keys do not know.
+ *
+ * @example
+ * ```ts
+ * const Sprite: Narrowed<{ texture: string }, { texture?: "board.cell" }> = component("Sprite", { texture: "" });
+ * Sprite({ texture: "board.cell" }).value.texture; // "board.cell"
+ * ```
+ */
+type Narrowed<Value extends object, Patch> = Omit<ComponentType<Value>, never> & ((patch?: Patch) => ComponentValue<Value>);
+/**
+ * A resource type made by `resource()`: one mutable object per world, created from a deep clone
+ * of the defaults on first read.
+ *
+ * @example
+ * ```ts
+ * const Pointer: ResourceType<{ x: number; y: number }> = resource("Pointer", { x: 0, y: 0 });
+ * Pointer.resourceName; // "Pointer"
+ * ```
+ */
+type ResourceType<Value extends object> = {
+  readonly resourceName: string;
+  readonly defaults: Readonly<Value>;
+};
+/**
+ * A query term marked as written by `mut()`. Its only effect is change detection.
+ *
+ * @example
+ * ```ts
+ * const written: Mut<{ x: number }> = mut(Transform);
+ * written.kind; // "mut"
+ * ```
+ */
+type Mut<Value extends object> = {
+  readonly kind: "mut";
+  readonly of: ComponentHandle<Value>;
+};
+/**
+ * A `mut()` term with its data type erased, as the world stores it.
+ *
+ * @example
+ * ```ts
+ * const term: AnyMut = { kind: "mut", of: { componentName: "Transform", kind: "component" } };
+ * ```
+ */
+type AnyMut = {
+  readonly kind: "mut";
+  readonly of: AnyComponentType;
+};
+/**
+ * One term of a query: a component type, a tag type, or a `mut()` of a component type.
+ *
+ * @example
+ * ```ts
+ * const terms: QueryTerm[] = [mut(Transform), Sprite, Held];
+ * ```
+ */
+type QueryTerm = AnyComponentType | AnyMut;
+/**
+ * The value a query yields for one term: writable for `mut()`, `true` for a tag, read-only for a
+ * plain component.
+ *
+ * @example
+ * ```ts
+ * type Written = ValueOf<Mut<{ x: number }>>; // { x: number }
+ * ```
+ */
+type ValueOf<Term> = Term extends Mut<infer Value> ? Value : Term extends TagType ? true : Term extends ComponentHandle<infer Value> ? Readonly<Value> : never;
+/**
+ * The value part of a query row, one entry per term, in term order.
+ *
+ * @example
+ * ```ts
+ * type Values = QueryValues<[TagType]>; // [true]
+ * ```
+ */
+type QueryValues<Terms extends readonly QueryTerm[]> = { -readonly [Index in keyof Terms]: ValueOf<Terms[Index]> };
+/**
+ * One row a query yields: the entity, then one value per term.
+ *
+ * @example
+ * ```ts
+ * type Row = QueryTuple<[ComponentType<{ x: number }>]>; // [Entity, Readonly<{ x: number }>]
+ * ```
+ */
+type QueryTuple<Terms extends readonly QueryTerm[]> = [Entity, ...QueryValues<Terms>];
+/**
+ * What a system receives next to its entities: the world, the mutable resources, the frozen model
+ * snapshot of the frame and the frame's `Time`. A system may read pure game rules; it never
+ * writes the model.
+ *
+ * @example
+ * ```ts
+ * const run = (entities: Iterable<[Entity]>, ctx: SystemContext): void => {
+ *   ctx.res(Pointer).x = 0;
+ *   ctx.time.delta; // 16
+ * };
+ * ```
+ */
+type SystemContext = {
+  readonly world: EcsApi;
+  res<Value extends object>(resource: ResourceType<Value>): Value;
+  readonly snapshot: Snapshot;
+  readonly time: Readonly<Time>;
+};
+/**
+ * A system definition, typed over its query tuple.
+ *
+ * @example
+ * ```ts
+ * const bob: SystemDefinition<[ComponentType<{ y: number }>]> = {
+ *   name: "bob",
+ *   phase: "animate",
+ *   query: [Transform],
+ *   run: entities => {
+ *     for (const [, transform] of entities) transform.y; // read-only
+ *   }
+ * };
+ * ```
+ */
+type SystemDefinition<Terms extends readonly QueryTerm[]> = {
+  readonly name: string;
+  readonly phase: WorldPhase;
+  readonly query: Terms;
+  run(entities: Iterable<QueryTuple<Terms>>, ctx: SystemContext): void;
+};
+/**
+ * A system with its query tuple erased, as the world stores it.
+ *
+ * @example
+ * ```ts
+ * const entry: AnySystem = { name: "bob", phase: "animate", query: [], run: () => {} };
+ * ```
+ */
+type AnySystem = {
+  readonly name: string;
+  readonly phase: WorldPhase;
+  readonly query: readonly QueryTerm[];
+  run(entities: Iterable<readonly unknown[]>, ctx: SystemContext): void;
+};
+/**
+ * One registered system and the frame it was registered in. A system registered during a frame
+ * runs from the next frame on.
+ *
+ * @example
+ * ```ts
+ * const entry: SystemEntry = { definition: bobSystem, frame: 12 };
+ * ```
+ */
+type SystemEntry = {
+  readonly definition: AnySystem;
+  readonly frame: number;
+};
+/**
+ * A structural change queued while a phase runs. Applied in call order when the phase ends.
+ *
+ * @example
+ * ```ts
+ * const command: Command = { kind: "remove", entity: 1_048_576, component: "Held" };
+ * ```
+ */
+type Command = {
+  kind: "attach";
+  entity: Entity;
+  components: readonly AnyComponentValue[];
+} | {
+  kind: "despawn";
+  entity: Entity;
+} | {
+  kind: "despawnOwnedBy";
+  owner: Owner;
+} | {
+  kind: "add";
+  entity: Entity;
+  value: AnyComponentValue;
+} | {
+  kind: "remove";
+  entity: Entity;
+  component: string;
+};
+/**
+ * A structural listener registered with `onAdded` or `onRemoved`.
+ *
+ * @example
+ * ```ts
+ * const hook: StructuralHook = (entity, value) => void entity + String(value);
+ * ```
+ */
+type StructuralHook = (entity: Entity, value: unknown) => void;
+/**
+ * The frozen model snapshot of one frame, kept so four phases read it once.
+ *
+ * @example
+ * ```ts
+ * const cached: FrameSnapshot = { frame: 12, snapshot: { player: {}, session: {}, rng: rngState } };
+ * ```
+ */
+type FrameSnapshot = {
+  frame: number;
+  snapshot: Snapshot;
+};
+/**
+ * ecs module state.
+ */
+type EcsState = {
+  generations: number[];
+  free: number[];
+  owners: Map<Entity, Owner>; /** Key is `"kind:name"` of the owner. */
+  byOwner: Map<string, Set<Entity>>;
+  types: Map<string, AnyComponentType>;
+  stores: Map<string, Map<Entity, object | true>>;
+  resources: Map<string, object>;
+  systems: Record<WorldPhase, SystemEntry[]>;
+  running: WorldPhase | undefined;
+  commands: Command[];
+  changed: Map<string, Set<Entity>>;
+  added: Map<string, StructuralHook[]>;
+  removed: Map<string, StructuralHook[]>;
+  ownerLeft: Array<(owner: Owner) => void>;
+  mode: WorldMode;
+  offFrame: Array<() => void>;
+  frameSnapshot: FrameSnapshot | undefined;
+};
+/**
+ * ecs module API, `app.world.ecs`: the screen as data. Plain-object components in one store per
+ * component type, generational entity ids, a mandatory owner, a command buffer applied between
+ * phases, coarse change detection and fixed phases driven by `time`.
+ *
+ * @example
+ * ```ts
+ * // A test owns its entities and reads them back.
+ * const entity = app.world.ecs.spawn({ kind: "plugin", name: "test" }, [Transform({ x: 10 })]);
+ * app.world.ecs.get(entity, Transform); // { x: 10, y: 0, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } }
+ * ```
+ */
+type EcsApi = {
+  /**
+   * Registers a system at the end of its phase list. A system registered during a frame runs
+   * from the next frame on.
+   *
+   * @param definition - The system, built with `system()`.
+   * @returns The remover; calling it twice is a no-op.
+   * @throws {Error} When a system of that name is already registered.
+   * @example
+   * ```ts
+   * // `text` registers its layout system when the plugin starts.
+   * const world = ctx.require(worldPlugin);
+   * const off = world.ecs.system(measureLabels); // runs from the next frame
+   *
+   * off(); // the plugin stops
+   * ```
+   */
+  system(definition: AnySystem): () => void;
+  /**
+   * Creates an entity. The id is reserved and returned at once, also inside a phase, where the
+   * components are attached when the phase ends.
+   *
+   * @param owner - Who owns the entity. Required by the type.
+   * @param components - Component and tag values the entity starts with.
+   * @returns The new entity id.
+   * @example
+   * ```ts
+   * // `ui` spawns a popup entity it owns, so closing the node frees it in one call.
+   * const entity = app.world.ecs.spawn({ kind: "node", name: "reward" }, [
+   *   Transform({ x: 540, y: 960 })
+   * ]);
+   * app.world.ecs.has(entity, Transform); // true
+   * ```
+   */
+  spawn(owner: Owner, components: readonly AnyComponentValue[]): Entity;
+  /**
+   * Removes every component of an entity, each firing `onRemoved`, frees the index and bumps the
+   * generation. A stale id is a no-op.
+   *
+   * @param entity - The entity to remove.
+   * @example
+   * ```ts
+   * // `ui` closes the popup it spawned. Asking again answers with the empty world.
+   * app.world.ecs.despawn(popup);
+   * app.world.ecs.has(popup, Transform); // false
+   * ```
+   */
+  despawn(entity: Entity): void;
+  /**
+   * Despawns exactly the entities of one owner and tells `projection` that the owner left.
+   *
+   * @param owner - The owner whose entities go.
+   * @example
+   * ```ts
+   * // A test cleans up after itself without touching the projections of the game.
+   * app.world.ecs.despawnOwnedBy({ kind: "plugin", name: "test" });
+   * app.world.ecs.snapshot(); // { mode: "live", entities: [], resources: {} }
+   * ```
+   */
+  despawnOwnedBy(owner: Owner): void;
+  /**
+   * Reads a component value. A stale id or a missing component gives `undefined`.
+   *
+   * @param entity - The entity to read.
+   * @param component - The component type.
+   * @returns The stored value, read-only, or `undefined`.
+   * @example
+   * ```ts
+   * // `input` asks whether the entity under the finger may be dragged.
+   * const world = ctx.require(worldPlugin);
+   * world.ecs.get(hit, Draggable); // { payload: { id: "i7" } }
+   * world.ecs.get(hit, DropTarget); // undefined: this item takes no drop
+   * ```
+   */
+  get<Value extends object>(entity: Entity, component: ComponentHandle<Value>): Readonly<Value> | undefined;
+  /**
+   * Shallow-merges a patch into a stored component and marks the entity changed for it. Never
+   * queued: a `set` inside a phase is visible to the next system of that phase.
+   *
+   * @param entity - The entity to write.
+   * @param component - The component type.
+   * @param patch - The fields to overwrite.
+   * @throws {Error} When the entity is stale or does not carry the component.
+   * @example
+   * ```ts
+   * // `input` moves the held view with the finger.
+   * const world = ctx.require(worldPlugin);
+   * world.ecs.set(held, Transform, { x: 420, y: 810 });
+   * world.ecs.get(held, Transform); // { x: 420, y: 810, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } }
+   * ```
+   */
+  set<Value extends object>(entity: Entity, component: ComponentHandle<Value>, patch: Partial<Value>): void;
+  /**
+   * Adds a component value. On an entity that already carries it the value is replaced and the
+   * entity is marked changed; no `onAdded` fires.
+   *
+   * @param entity - The entity to write.
+   * @param value - The component or tag value, built by calling its type.
+   * @example
+   * ```ts
+   * // `text` gives the label entity its display object once the atlas is there.
+   * const world = ctx.require(worldPlugin);
+   * world.ecs.add(label, Display({ object: bitmapText }));
+   * world.ecs.has(label, Display); // true
+   * ```
+   */
+  add(entity: Entity, value: AnyComponentValue): void;
+  /**
+   * Removes a component. Fires `onRemoved` when the entity carried it.
+   *
+   * @param entity - The entity to write.
+   * @param component - The component or tag type to drop.
+   * @example
+   * ```ts
+   * // `text` drops the display object when the label leaves the screen.
+   * const world = ctx.require(worldPlugin);
+   * world.ecs.remove(label, Display);
+   * world.ecs.has(label, Display); // false
+   * ```
+   */
+  remove(entity: Entity, component: AnyComponentType): void;
+  /**
+   * Tells whether an entity carries a component or tag. False for a stale id.
+   *
+   * @param entity - The entity to read.
+   * @param component - The component or tag type.
+   * @returns True when the entity carries it.
+   * @example
+   * ```ts
+   * // `input` never hit-tests a view that is on its way out.
+   * const world = ctx.require(worldPlugin);
+   * world.ecs.has(candidate, Exiting); // true while the merge animation plays
+   * ```
+   */
+  has(entity: Entity, component: AnyComponentType): boolean;
+  /**
+   * Adds a tag. Structural and idempotent.
+   *
+   * @param entity - The entity to write.
+   * @param tagType - The tag type.
+   * @example
+   * ```ts
+   * // `input` marks the view under the finger while the drag runs.
+   * const world = ctx.require(worldPlugin);
+   * world.ecs.tag(dragged, Held);
+   * world.ecs.has(dragged, Held); // true
+   * ```
+   */
+  tag(entity: Entity, tagType: TagType): void;
+  /**
+   * Removes a tag. Structural and idempotent.
+   *
+   * @param entity - The entity to write.
+   * @param tagType - The tag type.
+   * @example
+   * ```ts
+   * // `input` releases the view on pointer up.
+   * const world = ctx.require(worldPlugin);
+   * world.ecs.untag(dragged, Held);
+   * world.ecs.has(dragged, Held); // false
+   * ```
+   */
+  untag(entity: Entity, tagType: TagType): void;
+  /**
+   * Walks the store of the FIRST term in insertion order and keeps the entities that carry every
+   * term. Deterministic. A `mut()` term marks every yielded entity changed for that component.
+   *
+   * @param terms - Component types, tag types and `mut()` terms.
+   * @returns The matching rows: the entity and one value per term.
+   * @example
+   * ```ts
+   * // `renderer.sync` walks every sprite that has a place on the screen.
+   * for (const [entity, sprite, transform] of app.world.ecs.query(Sprite, Transform)) {
+   *   display.get(entity)?.position.set(transform.x, transform.y);
+   *   sprite.texture; // "board.item-red-1"
+   * }
+   * ```
+   */
+  query<const Terms extends readonly QueryTerm[]>(...terms: Terms): Iterable<QueryTuple<Terms>>;
+  /**
+   * Returns the one mutable value of a resource, created from a deep clone of its defaults on
+   * first read.
+   *
+   * @param resourceType - The resource type.
+   * @returns The mutable resource value.
+   * @example
+   * ```ts
+   * // `input` writes the pointer once per frame; every game system reads the same object.
+   * const world = ctx.require(worldPlugin);
+   * const pointer = world.ecs.resource(Pointer);
+   * pointer.down = true;
+   * ```
+   */
+  resource<Value extends object>(resourceType: ResourceType<Value>): Value;
+  /**
+   * Registers a listener for the moment a component is added, called when the structural change
+   * is applied. A throwing listener is logged and the others still run.
+   *
+   * @param component - The component type to watch.
+   * @param fn - Called with the entity and the stored value.
+   * @returns The remover; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // `renderer.sync` creates a Pixi object for every new sprite.
+   * const world = ctx.require(worldPlugin);
+   * const off = world.ecs.onAdded(Sprite, (entity, sprite) => {
+   *   objects.set(entity, makeSprite(sprite.texture));
+   * });
+   *
+   * off(); // the renderer stops
+   * ```
+   */
+  onAdded<Value extends object>(component: ComponentHandle<Value>, fn: (entity: Entity, value: Readonly<Value>) => void): () => void;
+  /**
+   * Registers a listener for the moment a tag is added: `tag` on an entity without it, or a spawn
+   * that carries it. A tag has no value, so the listener gets the entity only.
+   *
+   * @param tagType - The tag type to watch.
+   * @param fn - Called with the entity that got the tag.
+   * @returns The remover; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // `ui` shows the pressed look while `input` holds the `Pressed` tag on a button.
+   * const world = ctx.require(worldPlugin);
+   * const off = world.ecs.onAdded(Pressed, entity => markPointer(entity, "pressed", true));
+   *
+   * world.ecs.tag(button, Pressed); // markPointer(button, "pressed", true)
+   * off(); // ui stops
+   * ```
+   */
+  onAdded(tagType: TagType, fn: (entity: Entity) => void): () => void;
+  /**
+   * Registers a listener for the moment a component is removed.
+   *
+   * @param component - The component type to watch.
+   * @param fn - Called with the entity and the value it had.
+   * @returns The remover; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // `renderer.sync` destroys the Pixi object of a sprite that left.
+   * const world = ctx.require(worldPlugin);
+   * const off = world.ecs.onRemoved(Sprite, entity => {
+   *   objects.get(entity)?.destroy();
+   *   objects.delete(entity);
+   * });
+   *
+   * off(); // the renderer stops
+   * ```
+   */
+  onRemoved<Value extends object>(component: ComponentHandle<Value>, fn: (entity: Entity, value: Readonly<Value>) => void): () => void;
+  /**
+   * Registers a listener for the moment a tag is removed: `untag` on an entity that had it, or a
+   * despawn. The listener gets the entity only.
+   *
+   * @param tagType - The tag type to watch.
+   * @param fn - Called with the entity that lost the tag.
+   * @returns The remover; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // `ui` drops the pressed look when `input` releases the button.
+   * const world = ctx.require(worldPlugin);
+   * const off = world.ecs.onRemoved(Pressed, entity => markPointer(entity, "pressed", false));
+   *
+   * world.ecs.untag(button, Pressed); // markPointer(button, "pressed", false)
+   * off(); // ui stops
+   * ```
+   */
+  onRemoved(tagType: TagType, fn: (entity: Entity) => void): () => void;
+  /**
+   * The coarse change set of the frame, cleared in `time` phase `signals` after every `sync`
+   * system ran.
+   *
+   * @param component - The component type to ask about.
+   * @returns The entities marked changed for it this frame.
+   * @example
+   * ```ts
+   * // `renderer.sync` moves only what moved.
+   * for (const entity of app.world.ecs.changed(Transform)) {
+   *   const transform = app.world.ecs.get(entity, Transform);
+   *   display.get(entity)?.position.set(transform?.x ?? 0, transform?.y ?? 0);
+   * }
+   * ```
+   */
+  changed(component: AnyComponentType): Iterable<Entity>;
+  /**
+   * The effective mode: `"fast"` while the flow walks fast, otherwise the stored one.
+   *
+   * @returns The mode the frame runs in.
+   * @example
+   * ```ts
+   * // A test checks that a fast walk froze the tweens.
+   * app.flow.setMode("fast");
+   * app.world.ecs.mode(); // "fast", even though setMode was never called on the world
+   * ```
+   */
+  mode(): WorldMode;
+  /**
+   * Stores the world mode. `"fast"` finishes every motion and flushes every despawn queue at once.
+   *
+   * @param mode - The new stored mode.
+   * @example
+   * ```ts
+   * // A headless test wants the final picture without stepping frames.
+   * app.world.ecs.setMode("fast");
+   * app.world.ecs.mode(); // "fast"
+   * ```
+   */
+  setMode(mode: WorldMode): void;
+  /**
+   * The component type behind a name. A type registers itself on first use, so a name nobody
+   * wrote, read or queried yet is unknown.
+   *
+   * @param name - The storage name of the component.
+   * @returns The type, or `undefined` when the world never met it.
+   * @example
+   * ```ts
+   * // `text` resolves the component a label binds its number to.
+   * const world = ctx.require(worldPlugin);
+   * const type = world.ecs.typeOf("Coins"); // the Coins component, registered when it was written
+   * const pose = type === undefined ? undefined : world.ecs.get(counter, type);
+   *
+   * pose?.amount; // 120
+   * ```
+   */
+  typeOf(name: string): AnyComponent | undefined;
+  /**
+   * The whole world as plain JSON, sorted by entity index. A component value that is not JSON is
+   * left out and its name is listed in `skipped`.
+   *
+   * @returns The world as JSON: the mode, the entities and the resources.
+   * @example
+   * ```ts
+   * // A test asserts what the board holds after the first reconcile.
+   * app.world.ecs.snapshot();
+   * // { mode: "live", entities: [{ id: 1048576, index: 0, generation: 1,
+   * //   owner: { kind: "projection", name: "board.items" },
+   * //   components: { Layer: { name: "items" } }, skipped: [] }], resources: {} }
+   * ```
+   */
+  snapshot(): WorldSnapshot;
+};
+/**
+ * ecs methods injected into `projection`. Not public.
+ */
+type EcsInternal = {
+  /**
+   * Registers a listener for `despawnOwnedBy`, so `projection` can drop the views of an owner
+   * that left.
+   *
+   * @param fn - Called with the owner whose entities were despawned.
+   * @returns The remover.
+   */
+  onOwnerLeft(fn: (owner: Owner) => void): () => void;
+  /**
+   * The owner of an entity, which is also the liveness check: a stale id has none. `projection`
+   * asks before it hands out a view handle for an entity another plugin owns.
+   *
+   * @param entity - The entity to ask about.
+   * @returns The owner, or `undefined` when the id is stale.
+   */
+  ownerOf(entity: Entity): Owner | undefined;
+  /**
+   * Runs the systems of one phase, then flushes the command buffer.
+   *
+   * @param phase - The phase to run.
+   * @param time - The frame's `Time`.
+   */
+  runPhase(phase: WorldPhase, time: Readonly<Time>): void;
+  /**
+   * Applies the queued structural commands in call order.
+   */
+  flush(): void;
+  /**
+   * Clears every change set. Called in `time` phase `signals`.
+   */
+  clearChanges(): void;
+  /**
+   * Drops every entity, component, resource, system and hook.
+   */
+  clear(): void;
+};
+//#endregion
+//#region src/plugins/world/projection/types.d.ts
+/**
+ * How a layer orders the entities drawn in it.
+ *
+ * @example
+ * ```ts
+ * const sort: LayerSort = "y";
+ * ```
+ */
+type LayerSort = "none" | "y" | "order";
+/**
+ * One named layer of a scene. The order of the list is draw order.
+ *
+ * @example
+ * ```ts
+ * const layer: LayerSpec = { name: "items", sort: "y" };
+ * ```
+ */
+type LayerSpec = {
+  name: string;
+  sort: LayerSort;
+};
+/**
+ * Easing of a tween: one of the named curves the driver knows, or a function that gets the
+ * normalised time and returns the eased fraction.
+ *
+ * @example
+ * ```ts
+ * const ease: Ease = "outBack";
+ * ```
+ */
+type Ease = "linear" | "in" | "out" | "inOut" | "inCubic" | "outCubic" | "inOutCubic" | "inBack" | "outBack" | ((t: number) => number);
+/**
+ * What every motion returns: it can be finished, cancelled and asked whether it still runs.
+ * V3 `anim` hands out the same shape.
+ *
+ * @example
+ * ```ts
+ * const handle: MotionHandle = view.toRest(Transform);
+ * handle.active(); // true until the last frame wrote the exact target
+ * ```
+ */
+type MotionHandle = {
+  finish(): void;
+  cancel(): void;
+  active(): boolean;
+};
+/**
+ * What a motion hook returns. `void` means the hook wrote the component directly.
+ *
+ * @example
+ * ```ts
+ * const motion: Motion = undefined; // the hook called view.set and is already done
+ * ```
+ */
+type Motion = MotionHandle | void;
+/**
+ * Only the numeric fields of a component value: what a tween can interpolate.
+ *
+ * @example
+ * ```ts
+ * type Numbers = NumericFields<{ x: number; texture: string }>; // { x: number }
+ * ```
+ */
+type NumericFields<Value extends object> = { [Key in keyof Value as Value[Key] extends number ? Key : never]: Value[Key] };
+/**
+ * One keyframe segment of a track: the fraction of the track's `ms` it ends at (`0..1`), the
+ * curve it eases with (the track's `ease` when left out) and the numeric fields it reaches. A
+ * field it does not name holds where the segment before left it.
+ *
+ * @example
+ * ```ts
+ * // The swing of a popup board: past the rest pose at 42 % of the track, then home.
+ * const segments: TrackSegment[] = [
+ *   { at: 0.42, ease: "out", to: { y: 974, rotation: 0.087 } },
+ *   { at: 1, ease: "inOut", to: { y: 960, rotation: 0 } }
+ * ];
+ * ```
+ */
+type TrackSegment = {
+  at: number;
+  ease?: Ease;
+  to: Record<string, number>;
+};
+/**
+ * Options of `ViewHandle.tween`. An additive tween adds its delta over the value the absolute
+ * writer of the field holds, instead of owning the field. `segments` turns the tween into a
+ * keyframe walk: the segments run one after another over `ms` on one clock, and `to` is where the
+ * last one ends. `repeat` runs the walk again from its first segment when it ends: a number
+ * counts the extra runs, `"forever"` never ends. The world passes it to the driver unchanged;
+ * without a driver the target is written once.
+ *
+ * @example
+ * ```ts
+ * const options: TweenOptions = { ms: 350, ease: "out", delayMs: 40 };
+ * const walk: TweenOptions = { ms: 1000, segments: [{ at: 0.42, to: { y: 974 } }, { at: 1, to: { y: 960 } }] };
+ * const sway: TweenOptions = { ms: 2400, additive: true, repeat: "forever", segments: [{ at: 0.5, to: { rotation: 0.05 } }, { at: 1, to: { rotation: 0 } }] };
+ * ```
+ */
+type TweenOptions = {
+  ms: number;
+  ease?: Ease;
+  delayMs?: number;
+  additive?: boolean;
+  segments?: readonly TrackSegment[];
+  repeat?: number | "forever";
+};
+/**
+ * Options of `ViewHandle.toRest`. Defaults: the plugin's `settleMs` and ease `"out"`. `delayMs`
+ * lets a hook wait, for example for a flight to land, before the view comes home.
+ *
+ * @example
+ * ```ts
+ * const options: RestOptions = { ms: 200, delayMs: 120 };
+ * ```
+ */
+type RestOptions = {
+  ms?: number;
+  ease?: Ease;
+  delayMs?: number;
+};
+/**
+ * What the driver is told about one track: how long it runs, how it eases, how long it waits,
+ * whether it adds to the field or owns it, and the keyframe segments it walks. A track with
+ * segments walks them over `ms` on one clock and claims every field a segment names; its target
+ * `to` is the last segment's target. A track with `repeat` starts its walk again when it ends
+ * (a number counts the extra runs, `"forever"` never ends); the instant driver ignores it and
+ * writes the end pose once.
+ *
+ * @example
+ * ```ts
+ * const options: TrackOptions = { ms: 250, ease: "outBack", delayMs: 0, additive: false };
+ * const walk: TrackOptions = { ms: 1000, segments: [{ at: 0.42, to: { y: 974 } }, { at: 1, to: { y: 960 } }] };
+ * const twice: TrackOptions = { ms: 400, ease: "inOut", delayMs: 0, additive: true, repeat: 1 };
+ * ```
+ */
+type TrackOptions = {
+  ms: number;
+  ease?: Ease;
+  delayMs?: number;
+  additive?: boolean;
+  segments?: readonly TrackSegment[];
+  repeat?: number | "forever";
+};
+/**
+ * The tween engine behind `ViewHandle.tween`, `toRest` and `all`. `anim` installs one with
+ * `setDriver`; without it the world writes every target at once.
+ *
+ * A track reads its start values when its delay ends, writes the exact target on its last frame
+ * and goes through `ecs.set`, so `changed()` sees it. Muted fields are never written, also not on
+ * `finish()`.
+ *
+ * @example
+ * ```ts
+ * // `anim` hands the world its own tween core in `onStart`.
+ * const driver: TweenDriver = { track: startTrack, cancelAll: cancelTracksOf };
+ * const off = ctx.require(worldPlugin).projection.setDriver(driver);
+ *
+ * off(); // `anim` stopped: the world writes instantly again
+ * ```
+ */
+type TweenDriver = {
+  /**
+   * Starts one track on one component of one entity.
+   *
+   * @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.
+   * @param muted - The fields another writer owns, read at every write.
+   * @returns The motion handle of the track.
+   */
+  track(entity: Entity, component: AnyComponent, to: Record<string, number>, options: TrackOptions, muted: () => ReadonlySet<string>): MotionHandle;
+  /**
+   * Ends every track of one entity. Called when a view despawns and on every flush.
+   *
+   * @param entity - The entity whose tracks end.
+   */
+  cancelAll(entity: Entity): void;
+};
+/**
+ * One node of an element description, as `ui` builds it. The world never imports `ui`: it knows
+ * the shape structurally, carries it in `Tree` and hands it back unchanged.
+ *
+ * @example
+ * ```ts
+ * const node: DescriptionNode = { type: "box", props: { gap: 8 }, children: [] };
+ * ```
+ */
+type DescriptionNode = {
+  type: string;
+  key?: string;
+  props: object;
+  children: readonly unknown[];
+};
+/**
+ * What one `view(item)` call returns: the components of the item, or one description node that
+ * the world wraps as `Tree`.
+ *
+ * @example
+ * ```ts
+ * const components: ViewOutput = [Level({ level: 2 })];
+ * ```
+ */
+type ViewOutput = readonly AnyComponentValue[] | DescriptionNode;
+/**
+ * What a motion hook is handed: the one view it animates. A view never holds a reference to
+ * another view — `peer` answers with the other key's item, never with its entity.
+ *
+ * @example
+ * ```ts
+ * const enter = (view: ViewHandle<Item>, item: Item): Motion => {
+ *   view.set(Transform, { scale: 0 });
+ *   return view.toRest(Transform, { ms: 250 });
+ * };
+ * ```
+ */
+type ViewHandle<Item> = {
+  readonly entity: Entity;
+  readonly key: string;
+  get<Value extends object>(component: ComponentType<Value>): Readonly<Value> | undefined;
+  rest<Value extends object>(component: ComponentType<Value>): Readonly<Value> | undefined;
+  set<Value extends object>(component: ComponentType<Value>, patch: Partial<Value>): void;
+  tween<Value extends object>(component: ComponentType<Value>, to: Partial<NumericFields<Value>>, options: TweenOptions): MotionHandle;
+  toRest<Value extends object>(component: ComponentType<Value>, options?: RestOptions): MotionHandle;
+  all(handles: readonly Motion[]): MotionHandle;
+  peer(key: string): Item | undefined;
+};
+/**
+ * One `motion.change` hook, keyed by component name. `previous` and `next` are both passed, so a
+ * rollback that lowers a level can pick another motion than a level-up.
+ *
+ * @example
+ * ```ts
+ * const slide: ChangeHook<Item> = view => view.toRest(Transform, { ms: 350 });
+ * ```
+ */
+type ChangeHook<Item> = (view: ViewHandle<Item>, previous: Item, next: Item, hint?: Hint) => Motion;
+/**
+ * The `change` table of a projection: one hook per component name.
+ *
+ * @example
+ * ```ts
+ * const change: ChangeHooks<Item> = { Transform: view => view.toRest(Transform) };
+ * ```
+ */
+type ChangeHooks<Item> = {
+  readonly [component: string]: ChangeHook<Item>;
+};
+/**
+ * The motion hooks of a projection. Every one is optional; without a hook the component diff is
+ * written directly. `loop` starts what moves a view for its whole life (an additive sway, a spin):
+ * it is played wherever `enter` plays, next to it, and its motion is kept apart from the view's
+ * other motions, so a change never cancels it; it ends when the view dies.
+ *
+ * @example
+ * ```ts
+ * const motion: ProjectionMotion<Item> = {
+ *   change: { Transform: view => view.toRest(Transform, { ms: 350 }) }
+ * };
+ * // An order card that sways forever once it entered.
+ * const swaying: ProjectionMotion<Item> = {
+ *   loop: view =>
+ *     view.tween(Transform, { rotation: 0.05 }, { ms: 1200, additive: true, repeat: "forever" })
+ * };
+ * ```
+ */
+type ProjectionMotion<Item> = {
+  enter?(view: ViewHandle<Item>, item: Item, hint?: Hint): Motion;
+  loop?(view: ViewHandle<Item>): Motion;
+  exit?(view: ViewHandle<Item>, item: Item, hint?: Hint): Motion;
+  readonly change?: ChangeHooks<Item>;
+  settle?(view: ViewHandle<Item>, components: readonly string[]): Motion;
+};
+/**
+ * The motion hooks with the item type erased, as the world stores them.
+ *
+ * @example
+ * ```ts
+ * const stored: AnyProjectionMotion = { change: {} };
+ * ```
+ */
+type AnyProjectionMotion = {
+  enter?(view: ViewHandle<unknown>, item: unknown, hint?: Hint): Motion;
+  loop?(view: ViewHandle<unknown>): Motion;
+  exit?(view: ViewHandle<unknown>, item: unknown, hint?: Hint): Motion;
+  readonly change?: ChangeHooks<never>;
+  settle?(view: ViewHandle<unknown>, components: readonly string[]): Motion;
+};
+/**
+ * One projection: keyed items of the model turned into entities. `Item` is inferred from the
+ * return of `from`; `layer` and `lift` keep their literal types so a scene can check them.
+ *
+ * @example
+ * ```ts
+ * const spec: ProjectionSpec<Item, "items", "lifted", Player, Session> = {
+ *   name: "board.items",
+ *   layer: "items",
+ *   lift: "lifted",
+ *   from: player => player.board.items,
+ *   key: item => item.id,
+ *   view: item => [Item({ level: item.level })]
+ * };
+ * ```
+ */
+type ProjectionSpec<Item, LayerName extends string, LiftName extends string, Player, Session> = {
+  readonly name: string;
+  readonly layer: LayerName;
+  readonly lift?: LiftName;
+  from(player: Player, session: Session): readonly Item[] | Item; /** Omitted when `from` returns one plain object: the key is then the name of the projection. */
+  key?(item: Item): string;
+  view(item: Item): ViewOutput;
+  readonly motion?: ProjectionMotion<Item>;
+};
+/**
+ * A projection spec with its item and layer types erased, as the world stores it.
+ *
+ * @example
+ * ```ts
+ * const stored: AnyProjectionSpec = {
+ *   name: "board.items",
+ *   layer: "items",
+ *   from: () => [],
+ *   key: () => "",
+ *   view: () => []
+ * };
+ * ```
+ */
+type AnyProjectionSpec = {
+  readonly name: string;
+  readonly layer: string;
+  readonly lift?: string;
+  from(player: Json, session: Json): unknown;
+  key?(item: unknown): string;
+  view(item: unknown): ViewOutput;
+  readonly motion?: AnyProjectionMotion;
+};
+/**
+ * Why a reconcile runs. Merged over the frame; the cause table decides play or direct.
+ *
+ * @example
+ * ```ts
+ * const cause: Cause = "edge";
+ * ```
+ */
+type Cause = "edge" | "rollback" | "restore" | "load" | "mount" | "rerun";
+/**
+ * One live or exiting view: the entity of one key of one projection, its rest pose and the
+ * motions that still run on it.
+ *
+ * @example
+ * ```ts
+ * const view: View = {
+ *   entity: 1_048_576,
+ *   projection: "board.items",
+ *   key: "i7",
+ *   item: { id: "i7" },
+ *   rest: new Map(),
+ *   handles: [],
+ *   lifted: false,
+ *   dropWhenStill: false,
+ *   exiting: false
+ * };
+ * ```
+ */
+type View$1 = {
+  entity: Entity;
+  projection: string;
+  key: string;
+  item: unknown; /** The last output of `view(item)`, by component name: what the picture equals at rest. */
+  rest: Map<string, AnyComponentValue>;
+  handles: MotionHandle[];
+  lifted: boolean; /** `lift(false)` is waiting for the last motion to end. */
+  dropWhenStill: boolean;
+  exiting: boolean;
+};
+/**
+ * One mounted projection: its owner, the live views by key, the despawn queue and the items of
+ * the last reconcile.
+ *
+ * @example
+ * ```ts
+ * const mounted: Mounted = {
+ *   owner: { kind: "projection", name: "board.items" },
+ *   live: new Map(),
+ *   queue: [],
+ *   items: new Map()
+ * };
+ * ```
+ */
+type Mounted = {
+  owner: Owner;
+  live: Map<string, View$1>;
+  queue: View$1[];
+  items: Map<string, unknown>;
+};
+/**
+ * One track the projection started on the driver. The world keeps the component name and the
+ * handle, so it knows which components are driven without knowing how the driver runs them.
+ *
+ * @example
+ * ```ts
+ * const track: Track = { entity: 1_048_576, component: "Transform", handle: flight };
+ * track.handle.active(); // true while the flight runs
+ * ```
+ */
+type Track = {
+  entity: Entity;
+  component: string;
+  handle: MotionHandle;
+};
+/**
+ * The rest pose of one entity, by component name: the last output of `view(item)` for a view, or
+ * what `setRest` recorded for an element another plugin owns.
+ */
+type RestPose = Map<string, AnyComponentValue>;
+/**
+ * Where a keyed element lives: a plugin above registered it with `registerKey`, so `entityOf`
+ * and `keyOf` answer for it next to the views.
+ *
+ * @example
+ * ```ts
+ * const key: ProjectionKey = { projection: "hud", key: "coins" };
+ * ```
+ */
+type ProjectionKey = {
+  projection: string;
+  key: string;
+};
+/**
+ * What the next reconcile has to do: why it runs, which roots changed and whether `view` is
+ * forced for every item.
+ *
+ * @example
+ * ```ts
+ * const dirty: Dirty = { causes: ["edge"], roots: new Set(["player"]), force: false };
+ * ```
+ */
+type Dirty = {
+  causes: Cause[];
+  roots: Set<Root>;
+  force: boolean;
+};
+/**
+ * projection module state.
+ */
+type ProjectionState = {
+  specs: Map<string, AnyProjectionSpec>;
+  layers: readonly LayerSpec[];
+  mounted: Map<string, Mounted>;
+  byEntity: Map<Entity, View$1>;
+  dirty: Dirty | undefined;
+  hints: Hint[]; /** The tracks the projection started, with the handle that says whether they still run. */
+  tracks: Track[]; /** The tween engine `anim` installed, or `undefined`: then every target is written at once. */
+  driver: TweenDriver | undefined; /** The rest pose of an entity that is not a view, recorded by its owner through `setRest`. */
+  rests: Map<Entity, RestPose>; /** Projection name to key to the entity a plugin above registered under it. */
+  keys: Map<string, Map<string, Entity>>; /** The reverse of `keys`, so `keyOf` answers for a registered element too. */
+  keysByEntity: Map<Entity, ProjectionKey>; /** Entity to component name to the fields another writer owns. */
+  mutes: Map<Entity, Map<string, Set<string>>>;
+  offHints: Array<() => void>;
+};
+/**
+ * projection module API, `app.world.projection`: the bridge from the model to entities.
+ *
+ * @example
+ * ```ts
+ * // A test mounts the board and asks which entity carries one model key.
+ * app.world.projection.mount(["board.items"], { kind: "plugin", name: "test" });
+ * app.world.projection.entityOf("board.items", "i7"); // 1048576
+ * ```
+ */
+type ProjectionApi = {
+  /**
+   * Stores a projection spec. Nothing is drawn until `mount`.
+   *
+   * @param spec - The projection, built with `projection()`.
+   * @throws {Error} When a projection of that name is already registered.
+   * @example
+   * ```ts
+   * // A test registers one projection by hand instead of composing a feature.
+   * app.world.projection.register(boardItems);
+   * app.world.projection.entityOf("board.items", "i7"); // undefined: nothing is mounted yet
+   * ```
+   */
+  register(spec: AnyProjectionSpec): void;
+  /**
+   * Stores the layer list of the scene. The order of the list is draw order; every call stores a
+   * new frozen array.
+   *
+   * @param list - The layers, in draw order.
+   * @example
+   * ```ts
+   * // `scenes` switches to the board scene.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.setLayers([
+   *   { name: "board", sort: "none" },
+   *   { name: "items", sort: "y" },
+   *   { name: "lifted", sort: "none" }
+   * ]);
+   * ```
+   */
+  setLayers(list: ReadonlyArray<LayerSpec>): void;
+  /**
+   * The current layer list, empty before the first `setLayers`. A new list is a new reference, so
+   * a reader compares by identity.
+   *
+   * @returns The layers, in draw order.
+   * @example
+   * ```ts
+   * // `renderer.sync` rebuilds its containers only when the scene really changed.
+   * const current = app.world.projection.layers();
+   * if (current !== lastLayers) rebuildContainers(current); // [{ name: "board", sort: "none" }, ...]
+   * ```
+   */
+  layers(): ReadonlyArray<LayerSpec>;
+  /**
+   * Marks projections mounted under an owner and reconciles them at once, direct: a scene brings
+   * its own transition. Nothing is mounted when the call throws.
+   *
+   * @param names - Names of the projections to mount.
+   * @param owner - Who owns the entities of these projections.
+   * @throws {Error} For an unknown name, or a `layer` or `lift` the scene does not declare.
+   * @example
+   * ```ts
+   * // `scenes` mounts the projections of the board scene it just switched to.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.mount(["board.cells", "board.items"], { kind: "plugin", name: "scenes" });
+   * world.projection.entityOf("board.items", "i7"); // 1048576, the picture is already there
+   * ```
+   */
+  mount(names: readonly string[], owner: Owner): void;
+  /**
+   * Unmounts projections: every motion of their views is finished, and the live views and the
+   * despawn queue are despawned in the same call.
+   *
+   * @param names - Names of the projections to unmount.
+   * @example
+   * ```ts
+   * // `scenes` leaves the board scene.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.unmount(["board.cells", "board.items"]);
+   * world.projection.entityOf("board.items", "i7"); // undefined
+   * ```
+   */
+  unmount(names: readonly string[]): void;
+  /**
+   * A drop with no commit: cancels the view's motions and plays settle for every loose component.
+   * In mode `paused` or `fast` the rest pose is written at once. No-op for an entity that is not
+   * a live view.
+   *
+   * @param entity - The entity of the view that was dropped.
+   * @example
+   * ```ts
+   * // `input` released the finger over nothing, so the gate refused the answer.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.settle(held); // the item glides back to its cell over settleMs
+   * ```
+   */
+  settle(entity: Entity): void;
+  /**
+   * Hands a set of fields to another writer. Tracks never write them, also not on `finish()`.
+   *
+   * @param entity - The entity of the view.
+   * @param component - The component whose fields are taken over.
+   * @param fields - The field names the caller owns.
+   * @returns The remover; safe after the entity left, and a no-op when called twice.
+   * @example
+   * ```ts
+   * // `input` owns the position of the held view while the finger drags it.
+   * const world = ctx.require(worldPlugin);
+   * const release = world.projection.mute(held, Transform, ["x", "y"]);
+   *
+   * release(); // the finger let go
+   * ```
+   */
+  mute(entity: Entity, component: ComponentType<object>, fields: readonly string[]): () => void;
+  /**
+   * Moves a view into or out of its projection's `lift` layer. `lift(entity, false)` on a view
+   * that still moves takes effect when its last motion ends, so a settling view stays above the
+   * board until it is home.
+   *
+   * @param entity - The entity of the view.
+   * @param on - True to lift, false to drop back.
+   * @example
+   * ```ts
+   * // `input` lifts the item the finger picked up so it draws above the board.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.lift(held, true);
+   *
+   * world.projection.lift(held, false); // on release: takes effect when the settle motion ends
+   * ```
+   */
+  lift(entity: Entity, on: boolean): void;
+  /**
+   * The projection and key of an entity. Also answers for a view in the despawn queue and for an
+   * element registered with `registerKey`.
+   *
+   * @param entity - The entity to ask about.
+   * @returns The projection name and the key, or `undefined`.
+   * @example
+   * ```ts
+   * // `renderer.sync` labels its display objects for the inspector.
+   * app.world.projection.keyOf(1_048_576); // { projection: "board.items", key: "i7" }
+   * app.world.projection.keyOf(42); // undefined: not a view
+   * ```
+   */
+  keyOf(entity: Entity): ProjectionKey | undefined;
+  /**
+   * The rest value of one component of an entity: what a view holds when nothing animates it, or
+   * what `setRest` recorded for an element. Read-only and owner-free, so a plugin that owns no
+   * entity can aim at one.
+   *
+   * @param entity - A projection view or a registered element.
+   * @param component - The component whose rest value is asked.
+   * @returns The rest value, or `undefined` when the entity has none recorded.
+   * @example
+   * ```ts
+   * // `anim` builds a coin flight toward the counter: `at(target)` is the counter's rest pose.
+   * const world = ctx.require(worldPlugin);
+   * const counter = world.projection.entityOf("hud", "coins") ?? 0;
+   *
+   * world.projection.restOf(counter, Transform); // { x: 40, y: 120, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } }
+   * ```
+   */
+  restOf<Value extends object>(entity: Entity, component: ComponentType<Value>): Value | undefined;
+  /**
+   * The entity of one key of one projection: a live view, never the despawn queue, or an element
+   * a plugin above registered under that key.
+   *
+   * @param projection - Name of the projection.
+   * @param key - The model key.
+   * @returns The entity, or `undefined`.
+   * @example
+   * ```ts
+   * // `input` resolves the target of a scripted drag.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.entityOf("board.items", "i7"); // 1048576
+   * world.projection.entityOf("board.items", "gone"); // undefined
+   * ```
+   */
+  entityOf(projection: string, key: string): Entity | undefined;
+  /**
+   * The live view entities of a mounted projection, in the order of its model keys. A view that
+   * plays its exit is left out, and so is an element registered with `registerKey`. Every call
+   * hands out a new array.
+   *
+   * @param name - Name of the projection.
+   * @returns The entities, or `[]` when the projection is not mounted.
+   * @example
+   * ```ts
+   * // `ui` hosts the board inside a slot and parents every board item to it on reconcile.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.entitiesOf("board.items"); // [1048580, 1048581]
+   * world.projection.entitiesOf("shop.items"); // []: not mounted
+   * ```
+   */
+  entitiesOf(name: string): readonly Entity[];
+  /**
+   * Installs the tween engine every `ViewHandle.tween`, `toRest` and `all` then runs on. Without
+   * one the world writes every target at once and hands back an inactive handle.
+   *
+   * @param driver - The engine that runs the tracks.
+   * @returns The remover; it puts the instant writes back.
+   * @example
+   * ```ts
+   * // `anim` installs its tween core when it starts and takes it back when it stops.
+   * const world = ctx.require(worldPlugin);
+   * ctx.state.removeDriver = world.projection.setDriver(createDriver(ctx, ctx.state));
+   *
+   * ctx.state.removeDriver(); // onStop: motions are instant again
+   * ```
+   */
+  setDriver(driver: TweenDriver): () => void;
+  /**
+   * A view handle for an entity that is not a projection view, so an element another plugin owns
+   * can be animated the same way. `set`, `get`, `tween`, `toRest` and `all` work; `rest` answers
+   * what `setRest` recorded; `peer` answers `undefined`.
+   *
+   * @param entity - The entity of the element.
+   * @param owner - Who is asking; without it only the kind of the owner is checked.
+   * @returns The handle, or `undefined` for a projection view and for a foreign entity.
+   * @example
+   * ```ts
+   * // `ui` plays the `motion` prop of an element it owns.
+   * const world = ctx.require(worldPlugin);
+   * const handle = world.projection.viewOf(button, { kind: "plugin", name: "ui" });
+   *
+   * handle?.tween(Transform, { scale: 1.1 }, { ms: 120, ease: "outBack" });
+   * ```
+   */
+  viewOf(entity: Entity, owner: Owner): ViewHandle<unknown> | undefined;
+  /**
+   * Records what one component of an element looks like at rest, so `toRest` knows where home is.
+   *
+   * @param entity - The entity of the element.
+   * @param component - The component whose rest value is recorded.
+   * @param value - The value the element holds when nothing animates.
+   * @example
+   * ```ts
+   * // `ui` laid the coin counter out and tells the world where it belongs.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.setRest(counter, Transform, { x: 40, y: 120, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } });
+   *
+   * world.projection.viewOf(counter, { kind: "plugin", name: "ui" })?.rest(Transform); // { x: 40, y: 120, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } }
+   * ```
+   */
+  setRest<Value extends object>(entity: Entity, component: ComponentType<Value>, value: Value): void;
+  /**
+   * Gives an entity a projection and key of its own, so `entityOf` and `keyOf` answer for it next
+   * to the live views. That is how an element becomes a target for `anim`, `input` and `guide`.
+   *
+   * @param projection - Name the element is addressed under.
+   * @param key - Key the element is addressed under.
+   * @param entity - The entity of the element.
+   * @returns The remover; it drops the key again.
+   * @throws {Error} When a live view of that projection already holds the key.
+   * @example
+   * ```ts
+   * // `ui` publishes the coin counter of the HUD.
+   * const world = ctx.require(worldPlugin);
+   * const drop = world.projection.registerKey("hud", "coins", counter);
+   *
+   * world.projection.entityOf("hud", "coins"); // the entity of the counter
+   * drop(); // the element left the screen
+   * ```
+   */
+  registerKey(projection: string, key: string, entity: Entity): () => void;
+  /**
+   * Marks every mounted projection dirty and forces `view` for every item, so the next frame
+   * rebuilds the picture directly.
+   *
+   * @example
+   * ```ts
+   * // `i18n` switched the locale: every label has to be projected again.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.rerunAll(); // the next frame writes the new strings with no motion
+   * ```
+   */
+  rerunAll(): void;
+};
+/**
+ * projection methods the plugin root drives from the frame and the hooks. Not public.
+ */
+type ProjectionInternal = {
+  /**
+   * Records a commit. In fast mode it reconciles at once, direct.
+   *
+   * @param roots - The state roots the commit touched.
+   * @param cause - Why the commit happened.
+   */
+  markDirty(roots: readonly Root[], cause: Cause): void;
+  /**
+   * Reconciles when the world is dirty. Runs at the start of `time` phase `input`.
+   */
+  reconcileIfDirty(): void;
+  /**
+   * Empties the hint buffer. Runs once per frame, reconcile or not.
+   */
+  dropHints(): void;
+  /**
+   * Buffers one released hint.
+   *
+   * @param hint - The hint `flow.fx` released after a commit.
+   */
+  pushHint(hint: Hint): void;
+  /**
+   * Sweeps the views whose motions ended: the despawn queue, the convergence check and the
+   * pending drops. The tracks themselves are advanced by the driver.
+   */
+  sweep(): void;
+  /**
+   * Finishes every motion and flushes every despawn queue. Called when the mode turns `fast`.
+   */
+  flushAll(): void;
+  /**
+   * Drops the views of a projection whose owner despawned its entities.
+   *
+   * @param owner - The owner that left.
+   */
+  ownerLeft(owner: Owner): void;
+  /**
+   * Drops every view, track, mute and spec.
+   */
+  clear(): void;
+};
+declare namespace types_d_exports$1 {
+  export { AnyComponentType, AnyComponentValue, AnyProjectionSpec, AnySystem, Api$1 as Api, Cause, ChangeHook, ComponentHandle, ComponentType, ComponentValue, Config$1 as Config, Deps$1 as Deps, DescriptionNode, Ease, EcsApi, EcsModule, Entity, EntitySnapshot, Events$1 as Events, KernelSlice$1 as KernelSlice, LayerSort, LayerSpec, ModelCommitted, Motion, MotionHandle, Mut, Narrowed, NumericFields, Owner, ProjectionApi, ProjectionKey, ProjectionModule, ProjectionMotion, ProjectionSpec, QueryTerm, QueryTuple, ResourceType, RestOptions, State$1 as State, SystemContext, SystemDefinition, TagType, TrackOptions, TrackSegment, TweenDriver, TweenOptions, ViewHandle, ViewOutput, WorldCtx, WorldMode, WorldPhase, WorldSnapshot };
+}
+/**
+ * world plugin events.
+ *
+ * @example
+ * ```ts
+ * // A dev build counts what one reconcile did.
+ * createPlugin("reconcileLog", {
+ *   depends: [worldPlugin],
+ *   hooks: ctx => ({ "world:reconciled": counts => ctx.log.debug("reconciled", counts) })
+ * }); // one merge logs { mode: "play", entered: 0, changed: 1, exited: 1, ... }
+ * ```
+ */
+type Events$1 = {
+  /** Dev only (config `reconciledEvent`). Counts of one reconcile. */"world:reconciled": {
+    mode: "play" | "direct";
+    projections: number;
+    entered: number;
+    changed: number;
+    exited: number;
+    revived: number;
+    queued: number;
+    hintsRouted: number;
+    hintsDropped: number;
+  };
+};
+/**
+ * world plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { world: { settleMs: 250, reconciledEvent: true } } });
+ * ```
+ */
+type Config$1 = {
+  /** Duration of the built-in settle motion, in game milliseconds. */settleMs: number; /** Emit `world:reconciled` after every reconcile. Off in production; tests and the editor turn it on. */
+  reconciledEvent: boolean;
+};
+/**
+ * world plugin state: one branch per module.
+ */
+type State$1 = {
+  ecs: EcsState;
+  projection: ProjectionState;
+};
+/**
+ * world plugin API, `app.world`, grouped by module.
+ *
+ * @example
+ * ```ts
+ * app.world.ecs.mode(); // "live"
+ * app.world.projection.entityOf("board.items", "i7"); // 1048576
+ * ```
+ */
+type Api$1 = {
+  ecs: EcsApi;
+  projection: ProjectionApi;
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps$1 = {
+  time: Api$2;
+  model: Api$3;
+  flow: Api$4;
+};
+/**
+ * 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 event reaches the context the kernel hands the factories and `emit` is the
+ * kernel's own, world-typed one. No member of the context is cast.
+ */
+type KernelSlice$1 = PluginCtx<Config$1, State$1, Events$1> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the two modules.
+ */
+type WorldCtx = KernelSlice$1 & {
+  readonly deps: Deps$1;
+};
+/**
+ * Payload of the one event world listens to.
+ */
+type ModelCommitted = Events$2["model:committed"];
+/**
+ * Both halves of the `ecs` module: what a game calls and what `projection` gets injected.
+ */
+type EcsModule = EcsApi & EcsInternal;
+/**
+ * Both halves of the `projection` module: what a game calls and what the frame drives.
+ */
+type ProjectionModule = ProjectionApi & ProjectionInternal;
+//#endregion
+//#region src/plugins/renderer/host/types.d.ts
+/**
+ * host module state.
+ */
+type HostState = {
+  /** The Pixi module object, once `config.loadPixi()` resolved. */pixi: PixiModule | undefined;
+  app: PixiApplication | undefined;
+  canvas: HTMLCanvasElement | undefined; /** Where the canvas was appended. Read by `viewport` for its observer and its measurements. */
+  mount: HTMLElement | undefined;
+  kind: RendererKind;
+  ready: boolean; /** True from the moment a device is lost until the restore attempt ends. */
+  restoring: boolean; /** `viewport` and `sync` subscribe here; run once, after the first successful init. */
+  onReady: Array<() => void>; /** Run after a restore created a new application, where `onReady` must not run twice. */
+  onRestore: Array<() => void>; /** Run before the lost application is destroyed, while its display objects are still alive. */
+  onLoss: Array<() => void>;
+  cleanups: Array<() => void>;
+  unsupported: HTMLElement | undefined;
+};
+/**
+ * host module API, `app.renderer.host`. Everything a caller needs to know about the one Pixi
+ * application: whether it draws, what it draws with, and which canvas it draws on.
+ *
+ * @example
+ * ```ts
+ * // A game shows a DOM fallback while the renderer is inert or on the unsupported screen.
+ * if (!app.renderer.host.ready()) showFallback();
+ * app.renderer.host.kind(); // "webgpu"
+ * ```
+ */
+type HostApi = {
+  /**
+   * Tells whether the renderer draws. False while inert, while the device is lost and on the
+   * unsupported-device screen.
+   *
+   * @returns True after a successful init.
+   * @example
+   * ```ts
+   * // `assets` skips the texture upload of a bundle while nothing can draw it.
+   * const renderer = ctx.require(rendererPlugin);
+   * if (!renderer.host.ready()) return; // headless: the bundle stays on disk
+   * ```
+   */
+  ready(): boolean;
+  /**
+   * The backend Pixi chose, read once from the application after init.
+   *
+   * @returns `"webgpu"`, `"webgl"`, or `"none"` while inert or unsupported.
+   * @example
+   * ```ts
+   * // A game picks the WGSL or the GLSL source of its own filter.
+   * const source = app.renderer.host.kind() === "webgpu" ? wgsl : glsl; // "webgpu" in Chrome
+   * ```
+   */
+  kind(): RendererKind;
+  /**
+   * The canvas of the Pixi application. A WebGPU restore makes a NEW canvas, so a caller that
+   * holds listeners compares this with its stored canvas every frame.
+   *
+   * @returns The canvas, or `undefined` while inert and on the unsupported screen.
+   * @example
+   * ```ts
+   * // `input` re-attaches its pointer listeners when a restore replaced the canvas.
+   * const canvas = ctx.require(rendererPlugin).host.canvas();
+   * if (canvas !== undefined && canvas !== attached) attachPointerListeners(canvas);
+   * ```
+   */
+  canvas(): HTMLCanvasElement | undefined;
+  /**
+   * The Pixi module the renderer loaded lazily, so a plugin above draws with the same Pixi and
+   * still imports none of it.
+   *
+   * @returns The module once `ready()`, `undefined` while inert, lost or unsupported.
+   * @example
+   * ```ts
+   * // `text` builds the display object of a label out of the module the renderer loaded.
+   * const pixi = ctx.require(rendererPlugin).host.pixi();
+   * if (pixi === undefined) return; // headless: nothing is drawn
+   *
+   * const line = new pixi.BitmapText({ text: "+5", style: { fontFamily: "hud.body" } });
+   * ```
+   */
+  pixi(): PixiModule | undefined;
+};
+/**
+ * The textures the GPU holds: how many sources, and their estimated bytes.
+ *
+ * @example
+ * ```ts
+ * const usage: TextureUsage = { count: 2, bytes: 5_242_880 };
+ * ```
+ */
+type TextureUsage = {
+  count: number;
+  bytes: number;
+};
+/**
+ * host methods injected into `viewport`, `sync` and `monitor`, and driven by the plugin root. Not
+ * public.
+ */
+type HostInternal = {
+  /**
+   * Subscribes to the first successful init. Callbacks run in subscription order: `viewport`
+   * first, `sync` second.
+   *
+   * @param fn - Called once, after `ready` turned true.
+   */
+  onReady(fn: () => void): void;
+  /**
+   * Subscribes to a successful restore, where a new application and a new canvas exist but the
+   * one-time registrations of `onReady` must not run again.
+   *
+   * @param fn - Called after every successful restore.
+   */
+  onRestore(fn: () => void): void;
+  /**
+   * Subscribes to the moment just before a lost application is destroyed. This is the last point
+   * at which a display object the game owns can be saved out of the tree.
+   *
+   * @param fn - Called before every `destroy` of a lost application.
+   */
+  onLoss(fn: () => void): void;
+  /**
+   * The stage of the application. `sync` hangs its root container here.
+   *
+   * @returns The stage, or `undefined` while inert.
+   */
+  stage(): PixiContainer | undefined;
+  /**
+   * Where the canvas was appended. `viewport` observes and measures it.
+   *
+   * @returns The mount element, or `undefined` while inert.
+   */
+  mount(): HTMLElement | undefined;
+  /**
+   * Resizes the renderer to a CSS-pixel size. A no-op while nothing draws.
+   *
+   * @param width - New CSS width of the canvas.
+   * @param height - New CSS height of the canvas.
+   */
+  resize(width: number, height: number): void;
+  /**
+   * Draws one frame. A no-op while nothing draws, so a lost device costs nothing.
+   */
+  render(): void;
+  /**
+   * Draws the stage into a PNG over the whole canvas. A failed read is logged.
+   *
+   * @returns A PNG data URL, or `undefined` while nothing draws or when Pixi could not read it.
+   */
+  extract(): Promise<string | undefined>;
+  /**
+   * The texture sources the GPU holds and their estimated memory, read at call time.
+   *
+   * @returns The usage; zero while nothing draws.
+   */
+  textures(): TextureUsage;
+  /**
+   * Runs the init sequence: resolve the mount, load Pixi, create the application, append the
+   * canvas, then run the `onReady` callbacks. A failure shows the unsupported-device screen.
+   *
+   * @returns Resolves when the application is up, or when the plugin decided to stay inert.
+   */
+  init(): Promise<void>;
+};
+//#endregion
+//#region src/plugins/renderer/viewport/types.d.ts
+/**
+ * The orientation a game is designed for, read from the framework config.
+ *
+ * @example
+ * ```ts
+ * const orientation: Orientation = "portrait";
+ * ```
+ */
+type Orientation = Config$2["orientation"];
+/**
+ * A point in reference units.
+ *
+ * @example
+ * ```ts
+ * const point: Point = { x: 540, y: 960 };
+ * ```
+ */
+type Point = {
+  x: number;
+  y: number;
+};
+/**
+ * A rectangle in CSS pixels inside the canvas.
+ *
+ * @example
+ * ```ts
+ * const frame: Rect = { x: 555, y: 0, width: 810, height: 1080 };
+ * ```
+ */
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+/**
+ * The part of the frame a notch, a home bar or a rounded corner covers, in reference units.
+ *
+ * @example
+ * ```ts
+ * const safeArea: SafeArea = { top: 47, right: 0, bottom: 34, left: 0 };
+ * ```
+ */
+type SafeArea = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+/**
+ * What a game lays its board out in: the drawn frame in reference units.
+ *
+ * @example
+ * ```ts
+ * const size: ViewportSize = {
+ *   width: 1080, height: 1920, scale: 0.5625, orientation: "portrait",
+ *   safeArea: { top: 47, right: 0, bottom: 34, left: 0 }
+ * };
+ * ```
+ */
+type ViewportSize = {
+  width: number;
+  height: number;
+  scale: number;
+  orientation: Orientation;
+  safeArea: SafeArea;
+};
+/**
+ * viewport module state.
+ */
+type ViewportState = {
+  /** The drawn rectangle inside the canvas, in CSS pixels. Bars fill the rest. */frame: Rect; /** CSS pixels per reference unit. */
+  scale: number;
+  /**
+   * The frame in reference units: the short side is at least `referenceSide`, the long side inside
+   * the safe area at least `referenceLong`.
+   */
+  reference: {
+    width: number;
+    height: number;
+  };
+  safeArea: SafeArea; /** The observer saw a new size; the `render` callback applies it before drawing. */
+  resizePending: boolean; /** The hidden element whose padding carries `env(safe-area-inset-*)`. */
+  probe: HTMLElement | undefined;
+  cleanups: Array<() => void>;
+};
+/**
+ * viewport module API, `app.renderer.viewport`. The map between the window and the reference
+ * space. Both sides fit: the short side holds `referenceSide`, the long side inside the safe area
+ * holds `referenceLong`, and the smaller scale wins, so a wide screen gets a wider reference space.
+ *
+ * @example
+ * ```ts
+ * // A portrait game in a 1920x1080 window: an 810x1080 frame with bars left and right, and the
+ * // 1920 reference long side decides the scale.
+ * app.renderer.viewport.size(); // { width: 1440, height: 1920, scale: 0.5625, ... }
+ * app.renderer.viewport.toReference(960, 540); // { x: 720, y: 960 }
+ * ```
+ */
+type ViewportApi = {
+  /**
+   * Maps a pointer event to reference units: `(client − canvas rect − frame offset) / scale`.
+   * The canvas rectangle is read at call time, so a scrolled or animated page still answers right.
+   *
+   * @param clientX - `event.clientX` of a pointer event.
+   * @param clientY - `event.clientY` of a pointer event.
+   * @returns The point in reference units. Inert: the input unchanged.
+   * @example
+   * ```ts
+   * // `input` turns every pointer event into reference units before it hit-tests.
+   * const renderer = ctx.require(rendererPlugin);
+   * const point = renderer.viewport.toReference(event.clientX, event.clientY);
+   * renderer.sync.hitTest(point.x, point.y, isLiveDraggable);
+   * ```
+   */
+  toReference(clientX: number, clientY: number): Point;
+  /**
+   * Maps a point in reference units to client CSS pixels, the coordinates of `event.clientX`:
+   * `canvas rect + frame offset + point × scale`. The inverse of `toReference`; the canvas
+   * rectangle is read at call time.
+   *
+   * @param point - A point in reference units.
+   * @returns The point in client CSS pixels, a fresh object. Inert: the same numbers, reference
+   *   units, since there is no canvas to place them on.
+   * @example
+   * ```ts
+   * // The `game.rect` source of the editor places Home's Play plank on the page. A 390x844
+   * // phone, the canvas at the top left: the scale is 390 / 1080.
+   * const renderer = ctx.require(rendererPlugin);
+   * renderer.viewport.toScreen({ x: 540, y: 960 }); // { x: 195, y: 346.666… }
+   * ```
+   */
+  toScreen(point: Point): Point;
+  /**
+   * The drawn frame in reference units, as a fresh object.
+   *
+   * @returns Width, height, scale, designed orientation and the safe area.
+   * @example
+   * ```ts
+   * // A board keeps its bottom row above the home bar of the phone.
+   * const { height, safeArea } = app.renderer.viewport.size();
+   * const bottom = height - safeArea.bottom; // 1920 - 34
+   * ```
+   */
+  size(): ViewportSize;
+};
+/**
+ * viewport methods injected into `sync` and driven by the plugin root. Not public.
+ */
+type ViewportInternal = {
+  /**
+   * Writes the frame offset and the scale onto the root container, so root-local coordinates ARE
+   * reference coordinates.
+   *
+   * @param root - The root container of `sync`.
+   */
+  apply(root: PixiContainer): void;
+  /**
+   * Creates the safe-area probe and the resize observer, and measures once.
+   */
+  start(): void;
+  /**
+   * Applies a pending resize: one per frame, before drawing.
+   *
+   * @returns True when the frame changed, so `sync` writes the root transform again.
+   */
+  applyPending(): boolean;
+};
+//#endregion
+//#region src/plugins/renderer/sync/types.d.ts
+/**
+ * Which component gave an entity its display object. `"adapter"` is a component a plugin above
+ * registered with `displays.provide`.
+ *
+ * @example
+ * ```ts
+ * const kind: ViewKind = "NineSlice";
+ * ```
+ */
+type ViewKind = "Sprite" | "NineSlice" | "Shape" | "Display" | "adapter";
+/**
+ * How a component of a plugin above becomes a display object. The renderer parents, orders and
+ * frees the object like a sprite; the plugin decides what it is.
+ *
+ * @example
+ * ```ts
+ * const adapter: DisplayAdapter<{ resolved: string }> = {
+ *   create: value => buildRuns(value.resolved),
+ *   update: (object, previous, next) => {
+ *     if (previous.resolved !== next.resolved) rebuild(object, next.resolved);
+ *   },
+ *   destroy: object => (object as Container).destroy({ children: true, texture: false })
+ * };
+ * ```
+ */
+type DisplayAdapter<Value extends object = object> = {
+  /**
+   * Builds the display object of one entity. Called on the first pass after the component
+   * appeared, and never while the renderer is inert.
+   *
+   * @param value - The component value.
+   * @param entity - The entity it sits on.
+   * @returns A Pixi container.
+   */
+  create(value: Readonly<Value>, entity: Entity): unknown;
+  /**
+   * Writes a changed component value onto the object the adapter built.
+   *
+   * @param object - What `create` returned.
+   * @param previous - The value of the last pass.
+   * @param next - The value now.
+   */
+  update(object: unknown, previous: Readonly<Value>, next: Readonly<Value>): void;
+  /**
+   * Frees the object. Called when the component or the entity leaves, and when the renderer stops.
+   *
+   * @param object - What `create` returned.
+   */
+  destroy(object: unknown): void;
+};
+/**
+ * One registration of `displays.provide`: the component, its adapter and the world hooks that
+ * watch the component.
+ */
+type DisplayEntry = {
+  component: ComponentHandle<object>;
+  adapter: DisplayAdapter; /** The `onAdded` and `onRemoved` removers of this registration. */
+  removers: Array<() => void>;
+};
+/**
+ * The rectangle a hit test checks, in the local space of the view: anchor already applied.
+ *
+ * @example
+ * ```ts
+ * const box: HitBox = { x: -32, y: -32, width: 64, height: 64 };
+ * ```
+ */
+type HitBox = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+/**
+ * What `sync` knows about one drawn entity.
+ *
+ * @example
+ * ```ts
+ * const view: View = {
+ *   object: sprite, kind: "Sprite", poolKey: "Sprite:board.cell", layer: "items",
+ *   textureKey: "board.cell", wrapper: undefined, placeholder: false, mask: undefined,
+ *   display: undefined, value: undefined, drawScale: { x: 1, y: 1 }, frameKey: "",
+ *   outline: undefined, hitBox: { x: -32, y: -32, width: 64, height: 64 }
+ * };
+ * ```
+ */
+type View = {
+  object: PixiContainer;
+  kind: ViewKind; /** `kind + ":" + texture key`, the pool this object goes back to. */
+  poolKey: string; /** Name of the layer container the object hangs in, or `""` while it is parented. */
+  layer: string;
+  textureKey: string; /** The container that holds this entity's children, created when it is first named a parent. */
+  wrapper: PixiContainer | undefined; /** No provider answered: the view draws the 64x64 magenta square until a bundle arrives. */
+  placeholder: boolean; /** The rectangle a `clip: true` shape masks its children with. */
+  mask: PixiGraphics | undefined; /** The registration that built the object, for a component a plugin above draws its own way. */
+  display: DisplayEntry | undefined; /** A copy of the component value the adapter last saw, so `update` gets an honest `previous`. */
+  value: Readonly<object> | undefined;
+  /**
+   * How much the object is stretched from its texture to the box it draws, per axis: box over
+   * texture for a sized sprite, 64 for the 1x1 placeholder, 1 for everything else.
+   */
+  drawScale: Point; /** The crop a `"cover"` sprite shows, as its `frames` key; `""` when it shows none. */
+  frameKey: string; /** The debug outline of a nine-slice, in its wrapper; `undefined` while debug is off. */
+  outline: PixiGraphics | undefined;
+  hitBox: HitBox;
+};
+/**
+ * The crop of a `"cover"` sprite: a texture that shows the part of `base` covering one box.
+ * Cached by texture key and box size, shared by the entities in `users`, and freed when the last
+ * of them lets go or when its base is destroyed.
+ *
+ * @example
+ * ```ts
+ * const frame: CoverFrame = { base: meadow, texture: meadowCut, users: new Set([1_048_576]) };
+ * ```
+ */
+type CoverFrame = {
+  base: PixiTexture;
+  texture: PixiTexture;
+  users: Set<Entity>;
+};
+/**
+ * One layer of the scene: its container and the sort rule its children follow.
+ *
+ * @example
+ * ```ts
+ * const entry: LayerEntry = { container: itemsContainer, sort: "y" };
+ * ```
+ */
+type LayerEntry = {
+  container: PixiContainer | undefined;
+  sort: LayerSort;
+};
+/**
+ * A texture source `assets` registered.
+ *
+ * @example
+ * ```ts
+ * const provider: TextureProvider = key => loaded.get(key);
+ * ```
+ */
+type TextureProvider = (key: string) => PixiTexture | undefined;
+/**
+ * Nine-slice borders in pixels: left, top, right, bottom.
+ *
+ * @example
+ * ```ts
+ * const borders: NineBorders = [12, 12, 12, 12];
+ * ```
+ */
+type NineBorders = readonly [number, number, number, number];
+/**
+ * Options of `textures.create`.
+ *
+ * @example
+ * ```ts
+ * const options: CreateTextureOptions = { nine: [12, 12, 12, 12] };
+ * ```
+ */
+type CreateTextureOptions = {
+  nine?: NineBorders;
+};
+/**
+ * The texture registry `assets` drives, `app.renderer.sync.textures`. The renderer makes and
+ * destroys Pixi textures on request; `assets` owns when that happens.
+ *
+ * @example
+ * ```ts
+ * // `assets` decoded a file, hands the bitmap over and answers for the key from then on.
+ * const texture = app.renderer.sync.textures.create(bitmap);
+ * app.renderer.sync.textures.invalidate(["board.cell"]);
+ * ```
+ */
+type TexturesApi = {
+  /**
+   * Adds a provider to the chain. The newest provider is asked first.
+   *
+   * @param fn - Answers a texture for an asset key, or `undefined`.
+   * @returns The remover; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // `assets` publishes its loaded bundles in onStart and takes them back in onStop.
+   * const renderer = ctx.require(rendererPlugin);
+   * const off = renderer.sync.textures.provide(key => ctx.state.loaded.get(key));
+   *
+   * off(); // `assets` stops
+   * ```
+   */
+  provide(fn: TextureProvider): () => void;
+  /**
+   * Makes a Pixi texture from a decoded image, so `assets` never imports Pixi.
+   *
+   * @param image - The decoded image.
+   * @param options - `nine` is left, top, right and bottom in pixels; it becomes the texture's
+   *   default nine-slice borders.
+   * @returns The new texture.
+   * @throws {Error} When the renderer does not draw.
+   * @example
+   * ```ts
+   * // `assets` uploads one file of a bundle it just decoded.
+   * const renderer = ctx.require(rendererPlugin);
+   * const bitmap = await createImageBitmap(await response.blob());
+   * const texture = renderer.sync.textures.create(bitmap, { nine: [12, 12, 12, 12] });
+   * ```
+   */
+  create(image: ImageBitmap | HTMLImageElement, options?: CreateTextureOptions): PixiTexture;
+  /**
+   * Destroys a texture and its source. Destroying the same texture twice is a no-op.
+   *
+   * @param texture - The texture to free.
+   * @example
+   * ```ts
+   * // `assets` unloads a bundle: first the views let go, then the GPU memory is freed.
+   * const renderer = ctx.require(rendererPlugin);
+   * renderer.sync.textures.invalidate(["board.cell"]);
+   * renderer.sync.textures.destroy(texture);
+   * ```
+   */
+  destroy(texture: PixiTexture): void;
+  /**
+   * Marks asset keys stale. Every view that uses one resolves again in the next pass, and the
+   * pooled objects of these keys are destroyed at once.
+   *
+   * @param keys - The asset keys a bundle brought or took away.
+   * @example
+   * ```ts
+   * // A lazy bundle arrived: the magenta placeholders become the art on the next frame.
+   * const renderer = ctx.require(rendererPlugin);
+   * renderer.sync.textures.invalidate(["board.chain-1", "board.chain-2"]);
+   * ```
+   */
+  invalidate(keys: readonly string[]): void;
+};
+/**
+ * The display registry a plugin above extends, `app.renderer.sync.displays`. `Sprite`,
+ * `NineSlice` and `Shape` are built in; everything else arrives as an adapter.
+ *
+ * @example
+ * ```ts
+ * // `text` teaches the renderer to draw its own component, and takes it back in onStop.
+ * const off = ctx.require(rendererPlugin).sync.displays.provide(Text, textAdapter);
+ * ```
+ */
+type DisplaysApi = {
+  /**
+   * Registers how a component becomes a display object. The renderer calls `create` on the first
+   * pass after the component appeared, `update` on every change, and `destroy` when it leaves.
+   *
+   * @param component - The component the plugin owns.
+   * @param adapter - How that component is built, written and freed.
+   * @returns The remover; calling it twice is a no-op. The views built with it stay until their
+   *   entities leave or the renderer stops.
+   * @example
+   * ```ts
+   * // `text` draws its labels with BitmapText, and stops drawing them when it stops.
+   * const renderer = ctx.require(rendererPlugin);
+   * const off = renderer.sync.displays.provide(Text, createTextAdapter(ctx));
+   *
+   * off(); // `text` stops: the renderer builds no new label
+   * ```
+   */
+  provide<Value extends object>(component: ComponentHandle<Value>, adapter: DisplayAdapter<Value>): () => void;
+};
+/**
+ * The bitmap fonts of the one Pixi application, `app.renderer.sync.fonts`. `assets` loads the
+ * files, `text` hands them over, the renderer owns the installed font.
+ *
+ * @example
+ * ```ts
+ * // `text` installs the font of a bundle that just landed, once.
+ * const renderer = ctx.require(rendererPlugin);
+ * const font = ctx.require(assetsPlugin).font("hud.body");
+ *
+ * if (font !== undefined && !renderer.sync.fonts.installed("hud.body")) {
+ *   renderer.sync.fonts.install("hud.body", font.fnt, font.texture);
+ * }
+ * ```
+ */
+type FontsApi = {
+  /**
+   * Installs a BMFont file and its page texture under an asset key, so a `BitmapText` with that
+   * key as its `fontFamily` draws with it.
+   *
+   * @param key - The asset key of the font.
+   * @param fnt - The `.fnt` file: BMFont text, BMFont XML or BMFont JSON.
+   * @param texture - The page texture `assets` uploaded.
+   * @throws {Error} When the renderer does not draw, which is every headless run.
+   * @example
+   * ```ts
+   * // `text` installs the boot font after the renderer came up.
+   * const renderer = ctx.require(rendererPlugin);
+   * const font = ctx.require(assetsPlugin).font("hud.body");
+   *
+   * if (renderer.host.ready() && font !== undefined) {
+   *   renderer.sync.fonts.install("hud.body", font.fnt, font.texture);
+   * }
+   * ```
+   */
+  install(key: string, fnt: string, texture: PixiTexture): void;
+  /**
+   * Tells whether a font key is installed in this application.
+   *
+   * @param key - The asset key of the font.
+   * @returns True when the font is there.
+   * @example
+   * ```ts
+   * // `text` measures with the real advance table only once the font is in the renderer.
+   * const renderer = ctx.require(rendererPlugin);
+   * renderer.sync.fonts.installed("hud.body"); // false before the boot bundle landed
+   * ```
+   */
+  installed(key: string): boolean;
+};
+/**
+ * The debug switches of the renderer.
+ *
+ * @example
+ * ```ts
+ * const switches: DebugSwitches = { nineSlice: true };
+ * ```
+ */
+type DebugSwitches = {
+  nineSlice: boolean;
+};
+/**
+ * The debug drawing of the renderer, `app.renderer.sync.debug`. The switch outlines every
+ * nine-slice at once; a single panel asks for its own outline with `NineSlice.debug` (`ui`:
+ * `style.debug`).
+ *
+ * @example
+ * ```ts
+ * // Check where every panel of the open popup is cut: cyan lines, red where corners overlap.
+ * app.renderer.sync.debug.nineSlice(true);
+ * app.renderer.sync.debug.state(); // { nineSlice: true }
+ * ```
+ */
+type DebugApi = {
+  /**
+   * Turns the outline of every nine-slice on or off. The outline strokes the bounds of the panel
+   * and the four lines Pixi cuts its texture at: cyan, red when the corners overlap or the texture
+   * is missing. A nine-slice whose own `debug` is true keeps its outline while the switch is off.
+   * The views are drawn again on the next pass.
+   *
+   * @param on - True to outline every nine-slice.
+   * @example
+   * ```ts
+   * // A dev build binds a key: "d" shows where the settings popup cuts its parchment and tabs.
+   * globalThis.addEventListener("keydown", event => {
+   *   if (event.key === "d") app.renderer.sync.debug.nineSlice(true);
+   * });
+   * // After the next frame the parchment 1000x1040 with insets 72/76 shows lines at x 72 and
+   * // 928, y 76 and 964.
+   * ```
+   */
+  nineSlice(on: boolean): void;
+  /**
+   * What the debug switches are set to, as a fresh object.
+   *
+   * @returns The switches.
+   * @example
+   * ```ts
+   * // An e2e test makes sure no outline is drawn before it compares a screenshot.
+   * app.renderer.sync.debug.state(); // { nineSlice: false }
+   * ```
+   */
+  state(): DebugSwitches;
+};
+/**
+ * sync module API, `app.renderer.sync`. The one owner of every display object: it builds them
+ * from components, sorts them inside the named layers of the scene and answers hit tests.
+ *
+ * @example
+ * ```ts
+ * // `input` turns a pointer position into the entity under the finger.
+ * app.renderer.sync.hitTest(540, 300, entity => !app.world.ecs.has(entity, Exiting)); // 1048576
+ * ```
+ */
+type SyncApi = {
+  /**
+   * The topmost entity whose hit box holds the point and which `accept` allows. Pure component
+   * math: Pixi world matrices are one frame behind at input time.
+   *
+   * @param x - Reference x.
+   * @param y - Reference y.
+   * @param accept - Filter of the caller: the first accepted entity wins.
+   * @returns The entity, or `undefined` when nothing was hit. Inert: always `undefined`.
+   * @example
+   * ```ts
+   * // `input` never picks a view that is on its way out.
+   * const renderer = ctx.require(rendererPlugin);
+   * const world = ctx.require(worldPlugin);
+   * renderer.sync.hitTest(540, 300, entity => !world.ecs.has(entity, Exiting)); // 1048576
+   * ```
+   */
+  hitTest(x: number, y: number, accept: (entity: Entity) => boolean): Entity | undefined;
+  /**
+   * The texture registry `assets` drives.
+   */
+  textures: TexturesApi;
+  /**
+   * The display registry a plugin above extends with its own component.
+   */
+  displays: DisplaysApi;
+  /**
+   * The bitmap fonts of the one application.
+   */
+  fonts: FontsApi;
+  /**
+   * The debug drawing: the nine-slice outline.
+   */
+  debug: DebugApi;
+  /**
+   * The Pixi object of an entity, for debugging and for the plugins that draw their own thing.
+   *
+   * @param entity - The entity to ask about.
+   * @returns The display object, or `undefined` when the entity draws nothing.
+   * @example
+   * ```ts
+   * // An e2e test reads the label the renderer wrote, to find the view in the Pixi tree.
+   * const object = app.renderer.sync.displayOf(entity);
+   * (object as { label: string }).label; // "Sprite#1048576 board.items:i5"
+   * ```
+   */
+  displayOf(entity: Entity): unknown | undefined;
+};
+/**
+ * sync methods driven by the plugin root and by a device restore. Not public.
+ */
+type SyncInternal = {
+  /**
+   * Creates the root container, registers the world hooks and the `renderer.sync` system, and
+   * builds the views of the entities that already exist.
+   */
+  start(): void;
+  /**
+   * Drops every view, rebuilds the root, the layers and every view. Used after a restore, where
+   * the old application and all its objects are gone.
+   */
+  rebuildAll(): void;
+  /**
+   * One pass over the change sets: removed, layers, added, changed, invalidated keys.
+   */
+  pass(): void;
+  /**
+   * Lets go of the whole tree while it is still alive: the objects the game owns are detached,
+   * the pooled ones are destroyed. Called just before a lost application is destroyed.
+   */
+  forget(): void;
+  /**
+   * The root container, so the plugin root can re-apply the viewport transform after a resize.
+   *
+   * @returns The root, or `undefined` while inert.
+   */
+  root(): PixiContainer | undefined;
+  /**
+   * How many display objects `sync` holds, for the counters of `monitor`.
+   *
+   * @returns The views of entities and the objects waiting in the pools.
+   */
+  counts(): SyncCounts;
+};
+/**
+ * The display objects `sync` holds: views of entities and pooled objects.
+ *
+ * @example
+ * ```ts
+ * const counts: SyncCounts = { views: 180, pooled: 24 };
+ * ```
+ */
+type SyncCounts = {
+  views: number;
+  pooled: number;
+};
+/**
+ * sync module state.
+ */
+type SyncState = {
+  /** The container the viewport transform is written on. Its children are the layers. */root: PixiContainer | undefined; /** The list last read from `world.projection.layers()`, compared by reference. */
+  layerList: ReadonlyArray<LayerSpec> | undefined;
+  layers: Map<string, LayerEntry>;
+  views: Map<Entity, View>; /** The back reference from a display object to its entity. */
+  entityOf: Map<object, Entity>;
+  pools: Map<string, PixiContainer[]>;
+  pooled: number;
+  providers: TextureProvider[]; /** The components a plugin above draws its own way, in registration order. */
+  adapters: DisplayEntry[]; /** The bitmap fonts installed in this application, by asset key. */
+  fonts: Map<string, PixiBitmapFont>; /** The global Pixi cache the fonts were registered in, so `onStop` can take them out again. */
+  fontCache: PixiModule["Cache"] | undefined; /** Texture key to the entities that use it, for `invalidate`. */
+  byKey: Map<string, Set<Entity>>; /** The crops of `"cover"` sprites, by `key@widthxheight`. */
+  frames: Map<string, CoverFrame>;
+  invalidated: Set<string>; /** Keys already reported missing, so one key warns once. */
+  warned: Set<string>;
+  added: Set<Entity>;
+  removed: Set<Entity>; /** Entities whose `Parent` was removed: `world` marks no change then, only `onRemoved` fires. */
+  reparented: Set<Entity>; /** The debug switches, from `config.debug` and `debug.nineSlice`. */
+  debug: DebugSwitches; /** The nine-slice switch moved: the next pass writes every nine-slice again. */
+  outlinesStale: boolean;
+  cleanups: Array<() => void>;
+};
+//#endregion
+//#region src/plugins/renderer/monitor/types.d.ts
+/**
+ * The counters of the renderer, for a stats panel or a frame-budget check. Plain numbers, so the
+ * object goes through `JSON.stringify` as it is.
+ *
+ * @example
+ * ```ts
+ * const stats: RenderStats = { fps: 60, frameMs: 3.4, textures: 12, textureMb: 41.25, views: 180, pooled: 24 };
+ * ```
+ */
+type RenderStats = {
+  /**
+   * Frames drawn per second, measured over the last full second of `clock` time. 0 before the
+   * first second, while inert, and when no frame was drawn in the last second (a paused clock).
+   */
+  fps: number;
+  /**
+   * Mean milliseconds of `clock` time one frame took over that second, CPU side: from the
+   * renderer's callback in phase `input` to the end of `render`.
+   */
+  frameMs: number; /** Live texture sources on the GPU: Pixi's `renderer.texture.managedTextures`, empty slots skipped. */
+  textures: number; /** Estimated GPU memory of those sources in MiB: 4 bytes per pixel, every mip level. */
+  textureMb: number; /** Display objects `sync` holds for entities. */
+  views: number; /** Display objects waiting in the pools. */
+  pooled: number;
+  /**
+   * Not counted, so always absent. Under WebGPU, Pixi 8.21 batches sprites and graphics straight
+   * onto the native render pass encoder (`encoder.renderPassEncoder.drawIndexed`), past
+   * `renderer.encoder.draw`, so no one place in Pixi sees every draw.
+   */
+  drawCalls?: number;
+};
+/**
+ * monitor module state: the open measuring window, the last closed one, and the captures that
+ * wait for a frame.
+ */
+type MonitorState = {
+  /** Clock time at the start of the frame being drawn; `undefined` between frames. */frameStart: number | undefined; /** Clock time at the start of the last frame, the far end of the next interval. */
+  lastStart: number | undefined; /** Clock milliseconds between frame starts, summed over the open window. */
+  windowMs: number; /** Intervals between frame starts in the open window. */
+  intervals: number; /** Clock milliseconds spent inside frames in the open window. */
+  workMs: number; /** Frames finished in the open window. */
+  frames: number; /** Frames per second of the last closed window. */
+  fps: number; /** Mean frame work of the last closed window, in milliseconds. */
+  frameMs: number; /** Callers of `capture()` waiting for the next drawn frame. */
+  captures: Array<(url: string | undefined) => void>;
+};
+/**
+ * monitor module API, on `app.renderer` itself: the counters of the renderer and, in a dev build,
+ * a picture of the frame. What the editor's `game.render` source and `game.capture` command read.
+ *
+ * @example
+ * ```ts
+ * // A headless test: nothing is drawn, so every counter is 0 and there is no picture.
+ * app.renderer.stats(); // { fps: 0, frameMs: 0, textures: 0, textureMb: 0, views: 0, pooled: 0 }
+ * await app.renderer.capture(); // undefined
+ * ```
+ */
+type MonitorApi = {
+  /**
+   * The counters of the renderer, as a fresh object. The frame timing is kept each frame without
+   * an allocation; the rest is read at call time from `sync` and Pixi. There is no `drawCalls`:
+   * Pixi 8.21 has no one draw point under WebGPU.
+   *
+   * @returns Frames per second, frame work, GPU textures and their memory, views, pooled objects.
+   *   Inert: all 0.
+   * @example
+   * ```ts
+   * // The editor's stats panel reads it every frame. Here the game drew one sprite for 51 frames,
+   * // 20 ms apart with 4 ms of work each, and its texture is not uploaded yet.
+   * app.renderer.stats(); // { fps: 50, frameMs: 4, textures: 0, textureMb: 0, views: 1, pooled: 0 }
+   * ```
+   */
+  stats(): RenderStats;
+  /**
+   * A PNG of the whole canvas, bars included, taken right after the next frame is drawn, so the
+   * picture shows the state the game just reached; at once while the clock is paused, since no
+   * frame comes then. Dev builds only: `__MOKU_GAME_DEV__` must be `true`.
+   *
+   * @returns A `data:image/png;base64,…` URL. `undefined` in a production build, while inert, lost
+   *   or unsupported, and when Pixi could not read the frame (logged with `ctx.log.error`).
+   * @example
+   * ```ts
+   * // The editor's capture button, on the dev page that set globalThis.__MOKU_GAME_DEV__ = true.
+   * const url = await app.renderer.capture(); // "data:image/png;base64,iVBORw0KGgo…"
+   * // The same call in a production build.
+   * await app.renderer.capture(); // undefined
+   * ```
+   */
+  capture(): Promise<string | undefined>;
+};
+/**
+ * monitor methods the frame drives. Not public.
+ */
+type MonitorInternal = {
+  /**
+   * Marks the start of a frame: closes an interval of the measuring window.
+   */
+  begin(): void;
+  /**
+   * Marks the end of a drawn frame: adds its work to the window, and hands the frame to the
+   * captures that wait for it.
+   */
+  end(): void;
+};
+/**
+ * What `monitor` gets injected: the modules it reads its counters from.
+ */
+type MonitorDeps = {
+  host: HostApi & HostInternal;
+  sync: SyncApi & SyncInternal;
+};
+declare namespace types_d_exports {
+  export { Api, AspectRange, BitmapFontData, Config, CoverFrame, CreateTextureOptions, DebugApi, DebugSwitches, Deps, DisplayAdapter, DisplayEntry, DisplaysApi, Events, FontsApi, HitBox, HostApi, HostInternal, HostModule, HostState, KernelSlice, LayerEntry, Modules, MonitorApi, MonitorDeps, MonitorInternal, MonitorModule, MonitorState, NineBorders, Orientation, PixiApplication, PixiBitmapFont, PixiContainer, PixiGraphics, PixiModule, PixiNineSliceSprite, PixiSprite, PixiTexture, Point, Rect, RenderStats, RendererCtx, RendererKind, SafeArea, State, SyncApi, SyncCounts, SyncInternal, SyncModule, SyncState, TeardownScope, TextureProvider, TextureUsage, TexturesApi, View, ViewKind, ViewportApi, ViewportInternal, ViewportModule, ViewportSize, ViewportState };
+}
+/**
+ * The part of Pixi the engine uses: the classes `sync` builds views from (a `Rectangle` frames the
+ * crop of a `"cover"` sprite), the bitmap-font pieces `fonts.install` needs, and the `BitmapText`
+ * a plugin above builds through `host.pixi()`. The module object never arrives through a static
+ * import: `config.loadPixi()` returns it, so a game without a screen carries no Pixi in its bundle.
+ *
+ * @example
+ * ```ts
+ * const pixi: PixiModule = await import("pixi.js");
+ * pixi.Texture.WHITE.width; // 1
+ * ```
+ */
+type PixiModule = Pick<typeof import("pixi.js"), "Application" | "BitmapFont" | "BitmapText" | "Cache" | "Container" | "Graphics" | "NineSliceSprite" | "Rectangle" | "Sprite" | "Texture" | "bitmapFontTextParser" | "bitmapFontXMLStringParser">;
+/**
+ * One Pixi application: renderer, canvas and stage.
+ */
+type PixiApplication = InstanceType<PixiModule["Application"]>;
+/**
+ * A Pixi display object. `Sprite` and `NineSliceSprite` are containers too, so every view is one.
+ */
+type PixiContainer = InstanceType<PixiModule["Container"]>;
+/**
+ * A Pixi sprite.
+ */
+type PixiSprite = InstanceType<PixiModule["Sprite"]>;
+/**
+ * A Pixi nine-slice sprite.
+ */
+type PixiNineSliceSprite = InstanceType<PixiModule["NineSliceSprite"]>;
+/**
+ * A Pixi graphics object: what a `Shape` component is drawn with, and what clips its children.
+ */
+type PixiGraphics = InstanceType<PixiModule["Graphics"]>;
+/**
+ * A Pixi texture. `assets` owns its lifetime; the renderer only makes and destroys it on request.
+ */
+type PixiTexture = InstanceType<PixiModule["Texture"]>;
+/**
+ * A bitmap font the renderer installed for a font asset key. One per key.
+ */
+type PixiBitmapFont = InstanceType<PixiModule["BitmapFont"]>;
+/**
+ * The parsed shape of a `.fnt` file: what `BitmapFont` is built from.
+ */
+type BitmapFontData = ConstructorParameters<PixiModule["BitmapFont"]>[0]["data"];
+/**
+ * Which backend the one application drew with, or `"none"` while it draws nothing.
+ *
+ * @example
+ * ```ts
+ * const kind: RendererKind = "webgpu";
+ * ```
+ */
+type RendererKind = "webgpu" | "webgl" | "none";
+/**
+ * renderer plugin events.
+ *
+ * @example
+ * ```ts
+ * // A game reports a lost GPU to its analytics; the pause itself is handled by `lifecycle`.
+ * createPlugin("gpuReport", {
+ *   depends: [rendererPlugin],
+ *   hooks: ctx => ({ "renderer:device-lost": ({ kind }) => ctx.log.warn("gpu-lost", { kind }) })
+ * }); // a lost WebGPU device logs { kind: "webgpu" }
+ * ```
+ */
+type Events = {
+  /** The GPU device or the WebGL context was lost; the game is paused until the restore lands. */"renderer:device-lost": {
+    kind: "webgpu" | "webgl";
+    reason: string;
+  };
+};
+/**
+ * The two numbers that bound the shape of the drawn frame: allowed long side / short side.
+ *
+ * @example
+ * ```ts
+ * const aspect: AspectRange = { min: 4 / 3, max: 21 / 9 };
+ * ```
+ */
+type AspectRange = {
+  min: number;
+  max: number;
+};
+/**
+ * renderer plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   plugins: [...screen],
+ *   pluginConfigs: { renderer: { mount: "#game", background: 0x101018, maxResolution: 2 } }
+ * });
+ * // A debug build of the fixture outlines every nine-slice from the first frame.
+ * createApp({ pluginConfigs: { renderer: { mount: "#game", debug: { nineSlice: true } } } });
+ * ```
+ */
+type Config = {
+  /** Where the canvas goes: a selector or an element. `undefined` keeps the plugin inert. */mount: string | HTMLElement | undefined; /** Clear colour. Also the colour of the bars around the frame. */
+  background: number; /** Antialias the whole canvas. Off by default: pixel art and sprites do not need it. */
+  antialias: boolean; /** Cap of `devicePixelRatio`. Memory grows with its square. */
+  maxResolution: number; /** Passed to Pixi. Pixi falls back to WebGL by itself. */
+  preference: "webgpu" | "webgl"; /** Allowed long side / short side of the frame. A window outside it gets bars. */
+  aspect: AspectRange; /** Display objects kept in all pools together. */
+  poolLimit: number; /** Text of the unsupported-device screen. */
+  unsupportedMessage: string; /** Loader seam. Tests pass a fake module. */
+  loadPixi: () => Promise<PixiModule>; /** Debug drawing at start. `app.renderer.sync.debug` switches it while the game runs. */
+  debug: DebugSwitches;
+};
+/**
+ * renderer plugin state: one branch per module.
+ */
+type State = {
+  host: HostState;
+  viewport: ViewportState;
+  sync: SyncState;
+  monitor: MonitorState;
+};
+/**
+ * renderer plugin API, `app.renderer`: grouped by module, and the two members of `monitor`,
+ * `stats()` and `capture()`, on the plugin itself.
+ *
+ * @example
+ * ```ts
+ * app.renderer.host.kind(); // "webgpu"
+ * app.renderer.viewport.size().width; // 1080, reference units
+ * app.renderer.sync.hitTest(540, 300, () => true); // 1048576
+ * app.renderer.stats().views; // 180
+ * ```
+ */
+type Api = {
+  host: HostApi;
+  viewport: ViewportApi;
+  sync: SyncApi;
+} & MonitorApi;
+/**
+ * Resolved dependency APIs. `clock` is the time source of the frame counters.
+ */
+type Deps = {
+  time: Api$2;
+  lifecycle: Api$5;
+  world: Api$1;
+  clock: Api$6;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `emit` is the kernel's own: `index.ts` writes `events` with an annotated `register`
+ * (core spec `14-EVENT-REGISTRATION.md` row 8), so the plugin's own event reaches the pre-typed
+ * `api` factory and no member of this context is cast.
+ */
+type KernelSlice = PluginCtx<Config, State, Events> & {
+  readonly global: Readonly<Config$2>;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the three modules.
+ */
+type RendererCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+/**
+ * Both halves of the `host` module: what a game calls and what the two modules above get injected.
+ */
+type HostModule = HostApi & HostInternal;
+/**
+ * Both halves of the `viewport` module: what a game calls and what `sync` and the frame drive.
+ */
+type ViewportModule = ViewportApi & ViewportInternal;
+/**
+ * Both halves of the `sync` module: what `input` and `assets` call and what the frame drives.
+ */
+type SyncModule = SyncApi & SyncInternal;
+/**
+ * Both halves of the `monitor` module: what a tool calls and what the frame drives.
+ */
+type MonitorModule = MonitorApi & MonitorInternal;
+/**
+ * The four modules in injection order.
+ */
+type Modules = {
+  host: HostModule;
+  viewport: ViewportModule;
+  sync: SyncModule;
+  monitor: MonitorModule;
+};
+/**
+ * What `onStop` receives: the frozen config and the plugin state, nothing else.
+ */
+type TeardownScope = {
+  readonly config: Readonly<Config>;
+  readonly state: State;
+};
+//#endregion
+export { ComponentHandle as A, SystemDefinition as B, ProjectionSpec as C, AnyComponent as D, ViewHandle as E, Mut as F, Narrowed as I, Owner as L, ComponentValue as M, Entity as N, AnyComponentType as O, EntitySnapshot as P, QueryTerm as R, ProjectionMotion as S, TrackSegment as T, TagType as V, LayerSort as _, types_d_exports as a, MotionHandle as b, Point as c, Config$1 as d, State$1 as f, Ease as g, DescriptionNode as h, State as i, ComponentType as j, AnyComponentValue as k, ViewportSize as l, ChangeHook as m, Config as n, RenderStats as o, types_d_exports$1 as p, PixiTexture as r, DebugSwitches as s, Api as t, Api$1 as u, LayerSpec as v, TrackOptions as w, NumericFields as x, Motion as y, ResourceType as z };