@zylem/game-lib 0.8.9 → 0.9.1

package/dist/api/game-lib.d.ts

@@ -22,6 +22,7 @@ import { BoundaryRicochet3DEntity } from '@zylem/behaviors';
 import { BoundaryRicochetCoordinator } from '@zylem/behaviors';
 import { BoundaryRicochetEntity } from '@zylem/behaviors';
 import { BoundaryRicochetUpdate } from '@zylem/behaviors';
+import { Box3 } from 'three';
 import { BRIDGE_READY_EVENT } from '@zylem/bridge';
 import { BridgeChannel } from '@zylem/bridge';
 import { BridgeDebugTool } from '@zylem/bridge';
@@ -35,6 +36,7 @@ import { BridgeVec3 } from '@zylem/bridge';
 import { BufferGeometry } from 'three';
 import { BurstParticlePresetOptions } from '@zylem/behaviors';
 import { Camera } from 'three';
+import { CameraPosePayload } from '@zylem/bridge';
 import { clamp } from 'three/tsl';
 import { Color } from 'three';
 import { ColorRepresentation } from 'three';
@@ -72,6 +74,10 @@ import { createTopDownMovementInputComponent } from '@zylem/behaviors';
 import { createTopDownMovementStateComponent } from '@zylem/behaviors';
 import { createTransformComponent } from '@zylem/behaviors';
 import { createTransformStore } from '@zylem/behaviors/core';
+import { CutsceneLoadPayload } from '@zylem/bridge';
+import { CutscenePlaybackState } from '@zylem/bridge';
+import { CutsceneStatusPayload } from '@zylem/bridge';
+import { CutsceneViewPayload } from '@zylem/bridge';
 import { defineBehavior } from '@zylem/behaviors';
 import { DefineBehaviorConfig } from '@zylem/behaviors';
 import { Destructible3DBehavior } from '@zylem/behaviors';
@@ -360,6 +366,7 @@ import { ThrusterState } from '@zylem/behaviors';
 import { ThrusterStateComponent } from '@zylem/behaviors';
 import { tickCooldowns } from '@zylem/behaviors';
 import { time } from 'three/tsl';
+import * as ToneNs from 'tone';
 import { TopDownMovementBehavior } from '@zylem/behaviors';
 import { TopDownMovementBehaviorOptions } from '@zylem/behaviors';
 import { TopDownMovementComponent } from '@zylem/behaviors';
@@ -431,6 +438,12 @@ export declare interface Action {
     reset(): void;
 }
 
+/**
+ * The active shot across every camera track. Tracks are prioritised in
+ * order, so a shot on the first camera track overrides one on the second.
+ */
+export declare function activeShot(definition: CutsceneDefinition, time: number): CameraShot | undefined;
+
 export declare const ACTOR_TYPE: unique symbol;
 
 declare type ActorOptions = BaseNode | ZylemActorOptions;
@@ -545,6 +558,62 @@ export declare type AspectRatioValue = (typeof AspectRatio)[keyof typeof AspectR
 
 export { atan }
 
+/**
+ * Tracks that actually make sound: when any track is soloed only the soloed,
+ * unmuted ones play; otherwise everything not muted.
+ */
+export declare function audibleTrackIds(tracks: readonly SongTrack[]): Set<string>;
+
+export declare type AudioClip = Static<typeof AudioClipSchema>;
+
+export declare const AudioClipSchema: _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"audio">;
+    id: _sinclair_typebox.TString;
+    trackId: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** URL of the audio file. */
+    url: _sinclair_typebox.TString;
+    /** Beats from the song start. */
+    start: _sinclair_typebox.TNumber;
+    /** Seconds trimmed from the start of the file. */
+    offset: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    /** Beats. */
+    length: _sinclair_typebox.TNumber;
+    /** Clip gain in dB. */
+    gain: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+}>;
+
+export declare type AudioItem = Static<typeof AudioItemSchema>;
+
+export declare const AudioItemSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    time: _sinclair_typebox.TNumber;
+    kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"song">, _sinclair_typebox.TLiteral<"sfx">]>;
+    /** Song slug for `song`, asset URL for `sfx`. */
+    ref: _sinclair_typebox.TString;
+    loop: _sinclair_typebox.TBoolean;
+    /** Gain in dB. */
+    volume: _sinclair_typebox.TNumber;
+}>;
+
+export declare type AudioTrack = Static<typeof AudioTrackSchema>;
+
+declare const AudioTrackSchema: _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"audio">;
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        time: _sinclair_typebox.TNumber;
+        kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"song">, _sinclair_typebox.TLiteral<"sfx">]>;
+        /** Song slug for `song`, asset URL for `sfx`. */
+        ref: _sinclair_typebox.TString;
+        loop: _sinclair_typebox.TBoolean;
+        /** Gain in dB. */
+        volume: _sinclair_typebox.TNumber;
+    }>>;
+}>;
+
 declare interface BaseCollisionOptions {
     /** Whether the body is static (fixed) or dynamic */
     static?: boolean;
@@ -674,6 +743,16 @@ declare type BaseNodeOptions<T = any> = BaseNode | Partial<T>;
 
 declare type BasicTypes = number | string | boolean;
 
+/**
+ * Pure timing and scheduling math for songs. Everything here runs without
+ * an AudioContext so the player, the offline renderer and the editor agree
+ * on when things happen.
+ */
+/** Quarter-note beats per bar: 4/4 → 4, 6/8 → 3, 3/4 → 3. */
+export declare function beatsPerBar(signature: TimeSignature): number;
+
+export declare function beatsToSeconds(beats: number, bpm: number): number;
+
 export { BehaviorDescriptor }
 
 export { BehaviorHandle }
@@ -850,6 +929,27 @@ export declare interface CameraFeedOptions {
     height?: number;
 }
 
+export declare type CameraKeyframe = Static<typeof CameraKeyframeSchema>;
+
+export declare const CameraKeyframeSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    /** Seconds from the cutscene start. */
+    time: _sinclair_typebox.TNumber;
+    position: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+        x: _sinclair_typebox.TNumber;
+        y: _sinclair_typebox.TNumber;
+        z: _sinclair_typebox.TNumber;
+    }>>;
+    lookAt: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+        x: _sinclair_typebox.TNumber;
+        y: _sinclair_typebox.TNumber;
+        z: _sinclair_typebox.TNumber;
+    }>>;
+    fov: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    /** Easing used to arrive at this keyframe from the previous one. */
+    easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+}>;
+
 /**
  * CameraManager orchestrates multiple cameras per stage.
  *
@@ -1044,6 +1144,12 @@ export declare interface CameraOptions {
  */
 export declare interface CameraPerspective {
     id: string;
+    /**
+     * Projection the Three.js camera must use. When omitted, the runtime keeps
+     * a perspective camera. Orthographic perspectives set this so a runtime
+     * switch replaces the camera instance.
+     */
+    projection?: CameraProjection;
     /** Compute the raw desired pose for this frame given the current context. */
     getBasePose(ctx: CameraContext): CameraPose;
     /** Optional defaults for smoothing and other pipeline settings. */
@@ -1136,6 +1242,62 @@ export declare interface CameraPose {
     lookAt?: Vector3;
 }
 
+export declare type CameraPoseDef = Static<typeof CameraPoseDefSchema>;
+
+declare const CameraPoseDefSchema: _sinclair_typebox.TObject<{
+    position: _sinclair_typebox.TObject<{
+        x: _sinclair_typebox.TNumber;
+        y: _sinclair_typebox.TNumber;
+        z: _sinclair_typebox.TNumber;
+    }>;
+    lookAt: _sinclair_typebox.TObject<{
+        x: _sinclair_typebox.TNumber;
+        y: _sinclair_typebox.TNumber;
+        z: _sinclair_typebox.TNumber;
+    }>;
+}>;
+
+export { CameraPosePayload }
+
+/** Which Three.js camera a perspective commits onto. */
+export declare type CameraProjection = 'perspective' | 'orthographic';
+
+export declare type CameraShot = Static<typeof CameraShotSchema>;
+
+export declare const CameraShotSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    cameraId: _sinclair_typebox.TString;
+    start: _sinclair_typebox.TNumber;
+    end: _sinclair_typebox.TNumber;
+    blend: _sinclair_typebox.TObject<{
+        /** Seconds spent blending from the previous shot's camera; 0 is a hard cut. */
+        duration: _sinclair_typebox.TNumber;
+        easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+    }>;
+}>;
+
+export declare type CameraTrack = Static<typeof CameraTrackSchema>;
+
+/** Camera tracks in priority order. */
+export declare function cameraTracks(definition: CutsceneDefinition): CameraTrack[];
+
+declare const CameraTrackSchema: _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"camera">;
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        cameraId: _sinclair_typebox.TString;
+        start: _sinclair_typebox.TNumber;
+        end: _sinclair_typebox.TNumber;
+        blend: _sinclair_typebox.TObject<{
+            /** Seconds spent blending from the previous shot's camera; 0 is a hard cut. */
+            duration: _sinclair_typebox.TNumber;
+            easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+        }>;
+    }>>;
+}>;
+
 /**
  * CameraWrapper is the user-facing camera handle returned by createCamera().
  * It provides convenience methods for target management, orbital controls,
@@ -1239,6 +1401,9 @@ declare interface CleanupFunction<T, TGlobals extends GlobalRecord = any> {
  */
 export declare function clearGlobalSubscriptions(): void;
 
+/** Clips whose window covers `beat` on a track. */
+export declare function clipsAt(song: SongDefinition, trackId: string, beat: number): Array<NoteClip | AudioClip>;
+
 /**
  * Closest point along an infinite line to a ray, as a distance along the line.
  *
@@ -1495,6 +1660,19 @@ export declare function createCone(...args: Array<ConeOptions>): ZylemCone;
  */
 export declare function createCooldownIcon(...args: Array<CooldownIconOptions>): ZylemCooldownIcon;
 
+/**
+ * Plays a cutscene against a live stage: drives the camera through a
+ * pipeline behavior, fires event/audio items as the playhead crosses them,
+ * and runs scene transitions through the renderer.
+ *
+ * ```ts
+ * const player = createCutscenePlayer(INTRO_CUTSCENE, { host: createStageCutsceneHost(stage) });
+ * player.on('complete', () => player.dispose());
+ * player.play();
+ * ```
+ */
+export declare function createCutscenePlayer(initial: CutsceneDefinition, options: CutscenePlayerOptions): CutscenePlayer;
+
 /**
  * Create a cylinder entity.
  * @param args Options or child nodes
@@ -1599,6 +1777,12 @@ declare interface CreateGameEntityOptions<T extends GameEntity<any>, CreateOptio
  */
 export declare function createGlobal<T>(path: string, defaultValue: T): T;
 
+/**
+ * Builds the synth and effects chain for an instrument definition. The
+ * returned `output` is not connected anywhere; the caller routes it.
+ */
+export declare function createInstrument(Tone: ToneModule, def: InstrumentDefinition): Instrument;
+
 export { createJumpConfig2D }
 
 export { createJumpConfig3D }
@@ -1669,6 +1853,17 @@ export { createPlatformer3DMovementComponent }
 
 export { createPlatformer3DStateComponent }
 
+/**
+ * Follow a target with per-axis delay or platform settling.
+ *
+ * Shifts `position` and `lookAt` by the same delta, so the perspective's
+ * offset stays intact and the framed point becomes the filtered focus.
+ *
+ * "On a platform" is inferred from the axis going quiet. Games do not have
+ * to supply a grounded flag.
+ */
+export declare function createPlatformFollow(options?: PlatformFollowOptions): CameraBehavior;
+
 /**
  * Create a pyramid entity.
  * @param args Options or child nodes
@@ -1681,6 +1876,13 @@ export { createShooter2DStateComponent }
 
 export { createSimulation }
 
+/**
+ * Plays a song on Tone.js's transport. The transport is shared, so creating
+ * a player disposes the previous one: one song plays at a time. Tone.js is
+ * loaded lazily; the first `play()` must follow a user gesture.
+ */
+export declare function createSongPlayer(definition: SongDefinition, options?: SongPlayerOptions): SongPlayer;
+
 export declare function createSphere(...args: Array<SphereOptions>): ZylemSphere;
 
 export declare function createSprite(...args: Array<SpriteOptions>): ZylemSprite;
@@ -1690,6 +1892,18 @@ export declare function createSprite(...args: Array<SpriteOptions>): ZylemSprite
  */
 export declare function createStage(...options: StageOptions): Stage;
 
+export declare function createStageCutsceneHost(stageLike: CutsceneStageLike, options?: StageCutsceneHostOptions): CutsceneHost;
+
+/**
+ * StarCraft-style pan on the XZ plane.
+ *
+ * The perspective (top-down or isometric) owns the angle. This behavior only
+ * slides the framed point: edge scroll, arrow or stick pan, and an optional
+ * follow target. Screen up maps to world −Z, which matches a top-down camera
+ * whose up vector is −Z.
+ */
+export declare function createStrategyPan(options?: StrategyPanOptions): StrategyPanBehavior;
+
 export declare function createText(...args: Array<TextOptions>): ZylemText;
 
 export { createThrusterInputComponent }
@@ -1721,6 +1935,509 @@ export declare function createZone(...args: Array<ZoneOptions>): ZylemZone;
 /** Default blend: plain crossfade between the two frames. */
 export declare const crossfadeTransitionShader: ZylemTransitionShader;
 
+/** Pipeline key the cutscene player registers its behavior under. */
+export declare const CUTSCENE_BEHAVIOR_KEY = "cutscene";
+
+export declare type CutsceneCamera = Static<typeof CutsceneCameraSchema>;
+
+/**
+ * Camera behavior that hands the pipeline a fixed pose each frame while a
+ * cutscene is playing. It runs after the game's own behaviors (high
+ * priority) so shots override follow/look-at logic, and it disables itself
+ * when the player has no pose (no active shot) so gameplay framing resumes.
+ *
+ * `damping` applies optional per-frame smoothing for follow cameras; the
+ * player passes 0 for authored moves so keyframes land exactly.
+ */
+export declare class CutsceneCameraBehavior implements CameraBehavior {
+    priority: number;
+    enabled: boolean;
+    private target;
+    private smoothed;
+    private damping;
+    /** Sets the pose to show; `null` releases the camera back to gameplay. */
+    setPose(pose: EvaluatedPose | null, damping?: number): void;
+    /** Snap smoothing state so the next frame lands exactly on the pose (seeks, cuts). */
+    snap(): void;
+    onDetach(): void;
+    update(ctx: CameraContext, pose: CameraPose): CameraPose;
+}
+
+export declare type CutsceneCameraKind = Static<typeof CutsceneCameraKindSchema>;
+
+declare const CutsceneCameraKindSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"static">, _sinclair_typebox.TLiteral<"dolly">, _sinclair_typebox.TLiteral<"follow">]>;
+
+export declare const CutsceneCameraSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"static">, _sinclair_typebox.TLiteral<"dolly">, _sinclair_typebox.TLiteral<"follow">]>;
+    /** Vertical field of view in degrees. */
+    fov: _sinclair_typebox.TNumber;
+    /** Base pose; `static` cameras hold it, keyframes and dollies start from it. */
+    pose: _sinclair_typebox.TObject<{
+        position: _sinclair_typebox.TObject<{
+            x: _sinclair_typebox.TNumber;
+            y: _sinclair_typebox.TNumber;
+            z: _sinclair_typebox.TNumber;
+        }>;
+        lookAt: _sinclair_typebox.TObject<{
+            x: _sinclair_typebox.TNumber;
+            y: _sinclair_typebox.TNumber;
+            z: _sinclair_typebox.TNumber;
+        }>;
+    }>;
+    /** `dolly` cameras ride this path over each shot. */
+    dollyId: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** Progress curve along the dolly path (0 → 1 over the shot). */
+    dollyEasing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+    /** Entity name a `follow` camera tracks, and what a dolly looks at when set. */
+    target: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** Offset from the target for `follow` cameras. */
+    offset: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+        x: _sinclair_typebox.TNumber;
+        y: _sinclair_typebox.TNumber;
+        z: _sinclair_typebox.TNumber;
+    }>>;
+    /** Smoothing for `follow` cameras, 0 (instant) … 1 (very slow). */
+    damping: _sinclair_typebox.TNumber;
+    keyframes: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        /** Seconds from the cutscene start. */
+        time: _sinclair_typebox.TNumber;
+        position: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+            x: _sinclair_typebox.TNumber;
+            y: _sinclair_typebox.TNumber;
+            z: _sinclair_typebox.TNumber;
+        }>>;
+        lookAt: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+            x: _sinclair_typebox.TNumber;
+            y: _sinclair_typebox.TNumber;
+            z: _sinclair_typebox.TNumber;
+        }>>;
+        fov: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        /** Easing used to arrive at this keyframe from the previous one. */
+        easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+    }>>;
+}>;
+
+export declare type CutsceneDefinition = Static<typeof CutsceneDefinitionSchema>;
+
+export declare const CutsceneDefinitionSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    /** Seconds. */
+    duration: _sinclair_typebox.TNumber;
+    /** Stage the cutscene was authored against; informational. */
+    stage: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNull]>;
+    skippable: _sinclair_typebox.TBoolean;
+    scenes: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        /** Seconds from the cutscene start. */
+        start: _sinclair_typebox.TNumber;
+        end: _sinclair_typebox.TNumber;
+        /** How the picture arrives at this scene's start. */
+        transitionIn: _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"cut">, _sinclair_typebox.TLiteral<"fade">, _sinclair_typebox.TLiteral<"wipe">, _sinclair_typebox.TLiteral<"radial">, _sinclair_typebox.TLiteral<"noise">, _sinclair_typebox.TLiteral<"cells">]>;
+            /** Seconds; ignored for `cut`. */
+            duration: _sinclair_typebox.TNumber;
+            easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+        }>;
+    }>>;
+    cameras: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"static">, _sinclair_typebox.TLiteral<"dolly">, _sinclair_typebox.TLiteral<"follow">]>;
+        /** Vertical field of view in degrees. */
+        fov: _sinclair_typebox.TNumber;
+        /** Base pose; `static` cameras hold it, keyframes and dollies start from it. */
+        pose: _sinclair_typebox.TObject<{
+            position: _sinclair_typebox.TObject<{
+                x: _sinclair_typebox.TNumber;
+                y: _sinclair_typebox.TNumber;
+                z: _sinclair_typebox.TNumber;
+            }>;
+            lookAt: _sinclair_typebox.TObject<{
+                x: _sinclair_typebox.TNumber;
+                y: _sinclair_typebox.TNumber;
+                z: _sinclair_typebox.TNumber;
+            }>;
+        }>;
+        /** `dolly` cameras ride this path over each shot. */
+        dollyId: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        /** Progress curve along the dolly path (0 → 1 over the shot). */
+        dollyEasing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+        /** Entity name a `follow` camera tracks, and what a dolly looks at when set. */
+        target: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        /** Offset from the target for `follow` cameras. */
+        offset: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+            x: _sinclair_typebox.TNumber;
+            y: _sinclair_typebox.TNumber;
+            z: _sinclair_typebox.TNumber;
+        }>>;
+        /** Smoothing for `follow` cameras, 0 (instant) … 1 (very slow). */
+        damping: _sinclair_typebox.TNumber;
+        keyframes: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TString;
+            /** Seconds from the cutscene start. */
+            time: _sinclair_typebox.TNumber;
+            position: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+                x: _sinclair_typebox.TNumber;
+                y: _sinclair_typebox.TNumber;
+                z: _sinclair_typebox.TNumber;
+            }>>;
+            lookAt: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+                x: _sinclair_typebox.TNumber;
+                y: _sinclair_typebox.TNumber;
+                z: _sinclair_typebox.TNumber;
+            }>>;
+            fov: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            /** Easing used to arrive at this keyframe from the previous one. */
+            easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+        }>>;
+    }>>;
+    dollies: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        points: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+            x: _sinclair_typebox.TNumber;
+            y: _sinclair_typebox.TNumber;
+            z: _sinclair_typebox.TNumber;
+        }>>;
+        closed: _sinclair_typebox.TBoolean;
+        /** Catmull-Rom tension; 0.5 is centripetal. */
+        tension: _sinclair_typebox.TNumber;
+    }>>;
+    tracks: _sinclair_typebox.TArray<_sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+        kind: _sinclair_typebox.TLiteral<"camera">;
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TString;
+            cameraId: _sinclair_typebox.TString;
+            start: _sinclair_typebox.TNumber;
+            end: _sinclair_typebox.TNumber;
+            blend: _sinclair_typebox.TObject<{
+                /** Seconds spent blending from the previous shot's camera; 0 is a hard cut. */
+                duration: _sinclair_typebox.TNumber;
+                easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+            }>;
+        }>>;
+    }>, _sinclair_typebox.TObject<{
+        kind: _sinclair_typebox.TLiteral<"event">;
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TString;
+            time: _sinclair_typebox.TNumber;
+            event: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+                type: _sinclair_typebox.TLiteral<"emit">;
+                /** Stage event name. */
+                name: _sinclair_typebox.TString;
+                payload: _sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>>;
+            }>, _sinclair_typebox.TObject<{
+                type: _sinclair_typebox.TLiteral<"playAnimation">;
+                /** Entity name. */
+                entity: _sinclair_typebox.TString;
+                /** Animation key as passed to `playAnimation({ key })`. */
+                key: _sinclair_typebox.TString;
+            }>, _sinclair_typebox.TObject<{
+                type: _sinclair_typebox.TLiteral<"playSong">;
+                /** Song slug or URL; resolved by the host. */
+                song: _sinclair_typebox.TString;
+                loop: _sinclair_typebox.TBoolean;
+            }>, _sinclair_typebox.TObject<{
+                type: _sinclair_typebox.TLiteral<"stopSong">;
+                song: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            }>, _sinclair_typebox.TObject<{
+                type: _sinclair_typebox.TLiteral<"setVariable">;
+                name: _sinclair_typebox.TString;
+                value: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>;
+            }>]>;
+        }>>;
+    }>, _sinclair_typebox.TObject<{
+        kind: _sinclair_typebox.TLiteral<"audio">;
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TString;
+            time: _sinclair_typebox.TNumber;
+            kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"song">, _sinclair_typebox.TLiteral<"sfx">]>;
+            /** Song slug for `song`, asset URL for `sfx`. */
+            ref: _sinclair_typebox.TString;
+            loop: _sinclair_typebox.TBoolean;
+            /** Gain in dB. */
+            volume: _sinclair_typebox.TNumber;
+        }>>;
+    }>]>>;
+}>;
+
+export declare type CutsceneEasing = Static<typeof CutsceneEasingSchema>;
+
+declare const CutsceneEasingSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+
+export declare type CutsceneEvent = Static<typeof CutsceneEventSchema>;
+
+export declare const CutsceneEventSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+    type: _sinclair_typebox.TLiteral<"emit">;
+    /** Stage event name. */
+    name: _sinclair_typebox.TString;
+    payload: _sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>>;
+}>, _sinclair_typebox.TObject<{
+    type: _sinclair_typebox.TLiteral<"playAnimation">;
+    /** Entity name. */
+    entity: _sinclair_typebox.TString;
+    /** Animation key as passed to `playAnimation({ key })`. */
+    key: _sinclair_typebox.TString;
+}>, _sinclair_typebox.TObject<{
+    type: _sinclair_typebox.TLiteral<"playSong">;
+    /** Song slug or URL; resolved by the host. */
+    song: _sinclair_typebox.TString;
+    loop: _sinclair_typebox.TBoolean;
+}>, _sinclair_typebox.TObject<{
+    type: _sinclair_typebox.TLiteral<"stopSong">;
+    song: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+}>, _sinclair_typebox.TObject<{
+    type: _sinclair_typebox.TLiteral<"setVariable">;
+    name: _sinclair_typebox.TString;
+    value: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>;
+}>]>;
+
+export declare interface CutsceneFrame {
+    scene: CutsceneScene | undefined;
+    shot: CameraShot | undefined;
+    camera: CutsceneCamera | undefined;
+    pose: EvaluatedPose | undefined;
+    /** 0…1 while blending in from the previous shot, else 1. */
+    blend: number;
+}
+
+/**
+ * What the player needs from the running game. `createStageCutsceneHost`
+ * builds one from a live stage; tests and the editor can hand in stubs.
+ */
+export declare interface CutsceneHost {
+    /** The camera the cutscene drives; resolved each frame so stage swaps are safe. */
+    camera: () => ZylemCamera | null;
+    /** World position of a named entity, for follow cameras and dolly look-ats. */
+    entityPosition?: (name: string) => Vec3Def | undefined;
+    playAnimation?: (entity: string, key: string) => void;
+    /** Stage event dispatch (`emit` events). */
+    dispatch?: (name: string, payload: Record<string, unknown>) => void;
+    setVariable?: (name: string, value: unknown) => void;
+    playSong?: (ref: string, options: {
+        loop: boolean;
+        volume: number;
+    }) => void;
+    stopSong?: (ref?: string) => void;
+    playSfx?: (url: string, options: {
+        volume: number;
+        loop: boolean;
+    }) => void;
+    /**
+     * Runs a picture transition into the new scene: snapshot the current frame
+     * and blend it into the frames that follow. Omit to hard-cut everywhere.
+     */
+    beginTransition?: (transition: SceneTransition, shader: ZylemTransitionShader | undefined) => void;
+}
+
+/** Total length: the declared duration, or the furthest scene end if longer. */
+export declare function cutsceneLength(definition: Pick<CutsceneDefinition, 'duration' | 'scenes'>): number;
+
+export { CutsceneLoadPayload }
+
+export { CutscenePlaybackState }
+
+export declare interface CutscenePlayer {
+    readonly definition: CutsceneDefinition;
+    readonly state: CutscenePlayerState;
+    /** Seconds. */
+    readonly time: number;
+    readonly length: number;
+    /** The pose the picture shows right now, if a shot is active. */
+    readonly pose: EvaluatedPose | undefined;
+    play(from?: number): void;
+    pause(): void;
+    /** Stops, rewinds, and returns the camera to gameplay. */
+    stop(): void;
+    seek(time: number): void;
+    /** Jumps to the end (when `skippable`) and completes. */
+    skip(): boolean;
+    /** Advances by `dt` seconds; only needed with `tick: 'manual'`. */
+    update(dt: number): void;
+    /** Swaps the definition in place, keeping time and state (live editing). */
+    setDefinition(definition: CutsceneDefinition): void;
+    on<K extends keyof CutscenePlayerEvents>(event: K, handler: CutscenePlayerEvents[K]): () => void;
+    dispose(): void;
+}
+
+export declare interface CutscenePlayerEvents {
+    time: (time: number) => void;
+    state: (state: CutscenePlayerState) => void;
+    scene: (scene: CutsceneScene | undefined) => void;
+    shot: (shot: CameraShot | undefined) => void;
+    event: (item: EventItem) => void;
+    audio: (item: AudioItem) => void;
+    complete: () => void;
+    skip: () => void;
+}
+
+export declare interface CutscenePlayerOptions {
+    host: CutsceneHost;
+    /**
+     * `auto` (default) advances on `requestAnimationFrame`; `manual` leaves it
+     * to the caller's `update(dt)` — e.g. a stage `update` hook, so the
+     * cutscene pauses with the game.
+     */
+    tick?: 'auto' | 'manual';
+    /** Maps a transition type to a blend shader (e.g. `createStageTransition({ pattern }).shader`). */
+    transitionShader?: (type: SceneTransitionType) => ZylemTransitionShader | undefined;
+    /** Fire events/audio crossed by a `seek`. Off by default: scrubbing should not trigger gameplay. */
+    fireEventsOnSeek?: boolean;
+    timeScale?: number;
+}
+
+export declare type CutscenePlayerState = 'idle' | 'playing' | 'paused' | 'finished';
+
+/**
+ * Editor preview of a cutscene inside the running game: answers the bridge's
+ * `cutscene:*` commands with a player bound to the current stage and reports
+ * progress back. Owned by `ZylemGame`; Director mode drives it.
+ */
+export declare class CutscenePreviewController {
+    private readonly getStage;
+    private readonly publish;
+    private readonly hostOptions;
+    private readonly publishView?;
+    private player;
+    private lastStatus;
+    /** A load that arrived before the stage existed; replayed by `stageReady()`. */
+    private pending;
+    private readonly viewInverse;
+    private readonly viewProjection;
+    private lastView;
+    constructor(getStage: () => ZylemStage | null, publish: (status: CutsceneStatusPayload) => void, hostOptions?: StageCutsceneHostOptions, publishView?: ((view: CutsceneViewPayload) => void) | undefined);
+    get active(): boolean;
+    /**
+     * The game reports itself running before its first stage finishes loading,
+     * so an editor that loads a cutscene straight away would find no stage.
+     * The game calls this once a stage is up; a held load runs then.
+     */
+    stageReady(): void;
+    load(payload: CutsceneLoadPayload): void;
+    play(from?: number): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    /** Drops the player because its stage is going away; a held load survives for the next stage. */
+    releaseStage(): void;
+    /**
+     * Once per rendered frame while a cutscene is loaded: publishes the
+     * camera's projection and the canvas box when either changed, so the
+     * editor's overlays track the view without polling.
+     */
+    frame(): void;
+    unload(): void;
+    /** The live camera as position + look-at, for "capture from viewport". */
+    cameraPose(): Omit<CameraPosePayload, 'requestId'> | null;
+    private report;
+}
+
+export declare type CutsceneScene = Static<typeof CutsceneSceneSchema>;
+
+export declare const CutsceneSceneSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    /** Seconds from the cutscene start. */
+    start: _sinclair_typebox.TNumber;
+    end: _sinclair_typebox.TNumber;
+    /** How the picture arrives at this scene's start. */
+    transitionIn: _sinclair_typebox.TObject<{
+        type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"cut">, _sinclair_typebox.TLiteral<"fade">, _sinclair_typebox.TLiteral<"wipe">, _sinclair_typebox.TLiteral<"radial">, _sinclair_typebox.TLiteral<"noise">, _sinclair_typebox.TLiteral<"cells">]>;
+        /** Seconds; ignored for `cut`. */
+        duration: _sinclair_typebox.TNumber;
+        easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+    }>;
+}>;
+
+/**
+ * A `CutsceneHost` bound to a live stage: drives the stage camera, resolves
+ * entities by name, dispatches stage events, writes stage variables, plays
+ * songs through `@zylem/game-lib/audio` (loaded on demand) and one-shots
+ * through Howler, and runs scene transitions on the stage renderer.
+ */
+/** What a stage-bound cutscene plays on: the public `Stage` wrapper or the internal stage. */
+export declare type CutsceneStageLike = ZylemStage | Stage;
+
+export { CutsceneStatusPayload }
+
+export declare type CutsceneTrack = Static<typeof CutsceneTrackSchema>;
+
+export declare const CutsceneTrackSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"camera">;
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        cameraId: _sinclair_typebox.TString;
+        start: _sinclair_typebox.TNumber;
+        end: _sinclair_typebox.TNumber;
+        blend: _sinclair_typebox.TObject<{
+            /** Seconds spent blending from the previous shot's camera; 0 is a hard cut. */
+            duration: _sinclair_typebox.TNumber;
+            easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+        }>;
+    }>>;
+}>, _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"event">;
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        time: _sinclair_typebox.TNumber;
+        event: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"emit">;
+            /** Stage event name. */
+            name: _sinclair_typebox.TString;
+            payload: _sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>>;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"playAnimation">;
+            /** Entity name. */
+            entity: _sinclair_typebox.TString;
+            /** Animation key as passed to `playAnimation({ key })`. */
+            key: _sinclair_typebox.TString;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"playSong">;
+            /** Song slug or URL; resolved by the host. */
+            song: _sinclair_typebox.TString;
+            loop: _sinclair_typebox.TBoolean;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"stopSong">;
+            song: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"setVariable">;
+            name: _sinclair_typebox.TString;
+            value: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>;
+        }>]>;
+    }>>;
+}>, _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"audio">;
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        time: _sinclair_typebox.TNumber;
+        kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"song">, _sinclair_typebox.TLiteral<"sfx">]>;
+        /** Song slug for `song`, asset URL for `sfx`. */
+        ref: _sinclair_typebox.TString;
+        loop: _sinclair_typebox.TBoolean;
+        /** Gain in dB. */
+        volume: _sinclair_typebox.TNumber;
+    }>>;
+}>]>;
+
+export { CutsceneViewPayload }
+
 export declare const CYLINDER_TYPE: unique symbol;
 
 /**
@@ -1755,6 +2472,8 @@ declare interface CylinderMeshOptions extends BaseMeshOptions {
 
 declare type CylinderOptions = BaseNode | Partial<ZylemCylinderOptions>;
 
+export declare function dbToGain(db: number): number;
+
 /** Resolves a UUID to the live entity owned by the active stage. */
 export declare type DebugEntityResolver = (uuid: string) => GameEntity<any> | null;
 
@@ -1945,16 +2664,57 @@ declare type DiskOptions = BaseNode | Partial<ZylemDiskOptions>;
  */
 export declare function dispatchStageState(): void;
 
+export declare type DollyPath = Static<typeof DollyPathSchema>;
+
+export declare const DollyPathSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    points: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        x: _sinclair_typebox.TNumber;
+        y: _sinclair_typebox.TNumber;
+        z: _sinclair_typebox.TNumber;
+    }>>;
+    closed: _sinclair_typebox.TBoolean;
+    /** Catmull-Rom tension; 0.5 is centripetal. */
+    tension: _sinclair_typebox.TNumber;
+}>;
+
+/** Point along a dolly path at `u` in 0…1 (arc-length parameterised). */
+export declare function dollyPointAt(path: DollyPath, u: number): Vec3Def;
+
 export { dot }
 
+/**
+ * Pure evaluation of a cutscene at a point in time: which scene and shot are
+ * active, where each camera is, and the blended pose the picture should
+ * show. Nothing here touches Three.js cameras or the stage, so the same code
+ * drives the runtime player, the editor's scrubbing, and the unit specs.
+ */
+export declare function easeValue(easing: CutsceneEasing, t: number): number;
+
 export { EditorToGameMessages }
 
+export declare type EffectType = Static<typeof EffectTypeSchema>;
+
+declare const EffectTypeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"reverb">, _sinclair_typebox.TLiteral<"delay">, _sinclair_typebox.TLiteral<"distortion">, _sinclair_typebox.TLiteral<"filter">]>;
+
 export { emitRuntimeGoal }
 
 export { emitRuntimeRicochet }
 
 export { emitRuntimeTriggerRegionEnter }
 
+export declare function encodeWav(buffer: PcmSource): ArrayBuffer;
+
+/** `encodeWav` as a `Blob` ready for upload or download. */
+export declare function encodeWavBlob(buffer: PcmSource): Blob;
+
+/**
+ * Loads Tone.js and resumes the AudioContext. Call from a click or key
+ * handler the first time; later calls are cheap.
+ */
+export declare function ensureAudio(): Promise<ToneModule>;
+
 declare interface Entity<T = any> {
     setup: (entity: T) => void;
     destroy: () => void;
@@ -2238,9 +2998,38 @@ export declare interface EntityTypeMap {
     [LINE_TYPE]: ZylemLine;
 }
 
+export declare type Envelope = Static<typeof EnvelopeSchema>;
+
+declare const EnvelopeSchema: _sinclair_typebox.TObject<{
+    attack: _sinclair_typebox.TNumber;
+    decay: _sinclair_typebox.TNumber;
+    sustain: _sinclair_typebox.TNumber;
+    release: _sinclair_typebox.TNumber;
+}>;
+
 /** Convert Euler angles (radians, XYZ order) to a quaternion. */
 export declare function eulerToQuaternion(rotation: Vec3): Quat;
 
+/**
+ * Where a camera is at `time` while `shot` is active: base pose, then dolly
+ * progress or follow target, then keyframes on top.
+ */
+export declare function evaluateCameraPose(camera: CutsceneCamera, definition: Pick<CutsceneDefinition, 'dollies'>, shot: Pick<CameraShot, 'start' | 'end'>, time: number, lookup?: TargetLookup): EvaluatedPose;
+
+/**
+ * Everything the picture needs at `time`: the active scene and shot, and the
+ * camera pose after blending from the previous shot when the shot asks for
+ * it. Without an active shot the pose is `undefined` and the gameplay camera
+ * keeps control.
+ */
+export declare function evaluateCutscene(definition: CutsceneDefinition, time: number, lookup?: TargetLookup): CutsceneFrame;
+
+export declare interface EvaluatedPose {
+    position: Vec3Def;
+    lookAt: Vec3Def;
+    fov: number;
+}
+
 /**
  * Reusable delegate for event emission and subscription.
  * Use via composition in Game, Stage, and Entity classes.
@@ -2276,6 +3065,73 @@ export declare class EventEmitterDelegate<TEvents extends Record<string, unknown
     dispose(): void;
 }
 
+export declare type EventItem = Static<typeof EventItemSchema>;
+
+export declare const EventItemSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    time: _sinclair_typebox.TNumber;
+    event: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+        type: _sinclair_typebox.TLiteral<"emit">;
+        /** Stage event name. */
+        name: _sinclair_typebox.TString;
+        payload: _sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>>;
+    }>, _sinclair_typebox.TObject<{
+        type: _sinclair_typebox.TLiteral<"playAnimation">;
+        /** Entity name. */
+        entity: _sinclair_typebox.TString;
+        /** Animation key as passed to `playAnimation({ key })`. */
+        key: _sinclair_typebox.TString;
+    }>, _sinclair_typebox.TObject<{
+        type: _sinclair_typebox.TLiteral<"playSong">;
+        /** Song slug or URL; resolved by the host. */
+        song: _sinclair_typebox.TString;
+        loop: _sinclair_typebox.TBoolean;
+    }>, _sinclair_typebox.TObject<{
+        type: _sinclair_typebox.TLiteral<"stopSong">;
+        song: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    }>, _sinclair_typebox.TObject<{
+        type: _sinclair_typebox.TLiteral<"setVariable">;
+        name: _sinclair_typebox.TString;
+        value: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>;
+    }>]>;
+}>;
+
+export declare type EventTrack = Static<typeof EventTrackSchema>;
+
+declare const EventTrackSchema: _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"event">;
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    items: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        time: _sinclair_typebox.TNumber;
+        event: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"emit">;
+            /** Stage event name. */
+            name: _sinclair_typebox.TString;
+            payload: _sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>>;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"playAnimation">;
+            /** Entity name. */
+            entity: _sinclair_typebox.TString;
+            /** Animation key as passed to `playAnimation({ key })`. */
+            key: _sinclair_typebox.TString;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"playSong">;
+            /** Song slug or URL; resolved by the host. */
+            song: _sinclair_typebox.TString;
+            loop: _sinclair_typebox.TBoolean;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"stopSong">;
+            song: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>, _sinclair_typebox.TObject<{
+            type: _sinclair_typebox.TLiteral<"setVariable">;
+            name: _sinclair_typebox.TString;
+            value: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNumber, _sinclair_typebox.TBoolean]>;
+        }>]>;
+    }>>;
+}>;
+
 export { exp }
 
 export { FacingAngle2DEntity }
@@ -2363,6 +3219,7 @@ export declare interface FirstPersonOptions {
  */
 export declare class FirstPersonPerspective implements CameraPerspective {
     readonly id = "first-person";
+    readonly projection: "perspective";
     readonly defaults: {
         damping: number;
     };
@@ -2447,6 +3304,7 @@ export declare interface Fixed2DOptions {
  */
 export declare class Fixed2DPerspective implements CameraPerspective {
     readonly id = "fixed-2d";
+    readonly projection: "orthographic";
     readonly defaults: {
         damping: number;
     };
@@ -2494,6 +3352,8 @@ export { FractureOptions }
 
 export { FractureOptionsInput }
 
+export declare function gainToDb(gain: number): number;
+
 export declare class Game<TGlobals extends BaseGlobals> implements IGame<TGlobals> {
     private wrappedGame;
     options: GameOptions<TGlobals>;
@@ -2635,6 +3495,10 @@ export declare class GameBridge {
      * @param announceTarget DOM node the `zylem:bridge:ready` event bubbles from
      */
     connect(host: GameBridgeHost, announceTarget?: EventTarget): void;
+    /** Cutscene playback progress for Director mode's transport. */
+    publishCutsceneStatus(status: CutsceneStatusPayload): void;
+    /** The previewing camera's projection, for Director mode's viewport overlays. */
+    publishCutsceneView(view: CutsceneViewPayload): void;
     disconnect(): void;
     /**
      * Run a swatch batch and report back.
@@ -2750,6 +3614,17 @@ export declare interface GameBridgeHost {
     applySwatches?(payload: EntityApplySwatchPayload & {
         opId: string;
     }): SwatchApplyOutcome;
+    /** Cutscene preview hooks (`cutscene:*`); publish progress via `publishCutsceneStatus`. */
+    cutscene?: {
+        load(payload: CutsceneLoadPayload): void;
+        play(from?: number): void;
+        pause(): void;
+        stop(): void;
+        seek(time: number): void;
+        unload(): void;
+    };
+    /** Describe the live camera (`camera:pose:get`), for capturing framing into a cutscene. */
+    cameraPose?(): Omit<CameraPosePayload, 'requestId'> | null;
 }
 
 /**
@@ -3590,6 +4465,9 @@ export { GameToEditorMessages }
 
 export { GameVariablePayload }
 
+/** The most recently created, still-live song player, if any. */
+export declare function getActiveSongPlayer(): SongPlayer | null;
+
 export { getCooldown }
 
 export { getCooldownStore }
@@ -3890,6 +4768,70 @@ declare class InstanceManager {
     private growPack;
 }
 
+/**
+ * A playable instrument: a Tone.js synth for the preset, its effects chain,
+ * and an output node the song player routes into a track channel.
+ */
+export declare interface Instrument {
+    readonly definition: InstrumentDefinition;
+    /** Connect this to a channel or destination. */
+    readonly output: ToneNs.ToneAudioNode;
+    /** Plays a note. `time` is in the Tone context clock (seconds); omit for now. */
+    trigger(pitch: number, duration: number, time?: number, velocity?: number): void;
+    /** Silences ringing notes. */
+    releaseAll(time?: number): void;
+    dispose(): void;
+}
+
+export declare type InstrumentDefinition = Static<typeof InstrumentDefinitionSchema>;
+
+export declare const InstrumentDefinitionSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    preset: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"synth">, _sinclair_typebox.TLiteral<"polySynth">, _sinclair_typebox.TLiteral<"fmSynth">, _sinclair_typebox.TLiteral<"amSynth">, _sinclair_typebox.TLiteral<"membraneSynth">, _sinclair_typebox.TLiteral<"metalSynth">, _sinclair_typebox.TLiteral<"noiseSynth">, _sinclair_typebox.TLiteral<"pluckSynth">]>;
+    oscillator: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"sine">, _sinclair_typebox.TLiteral<"square">, _sinclair_typebox.TLiteral<"sawtooth">, _sinclair_typebox.TLiteral<"triangle">]>>;
+    envelope: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+        attack: _sinclair_typebox.TNumber;
+        decay: _sinclair_typebox.TNumber;
+        sustain: _sinclair_typebox.TNumber;
+        release: _sinclair_typebox.TNumber;
+    }>>;
+    /** Output trim in dB. */
+    volume: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    effects: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"reverb">, _sinclair_typebox.TLiteral<"delay">, _sinclair_typebox.TLiteral<"distortion">, _sinclair_typebox.TLiteral<"filter">]>;
+        /** Dry/wet mix, 0–1. */
+        wet: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        /** Effect-specific settings forwarded to the Tone.js constructor. */
+        options: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TNumber, _sinclair_typebox.TString, _sinclair_typebox.TBoolean]>>>;
+    }>>>;
+}>;
+
+export declare type InstrumentEffect = Static<typeof InstrumentEffectSchema>;
+
+export declare const InstrumentEffectSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"reverb">, _sinclair_typebox.TLiteral<"delay">, _sinclair_typebox.TLiteral<"distortion">, _sinclair_typebox.TLiteral<"filter">]>;
+    /** Dry/wet mix, 0–1. */
+    wet: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    /** Effect-specific settings forwarded to the Tone.js constructor. */
+    options: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TNumber, _sinclair_typebox.TString, _sinclair_typebox.TBoolean]>>>;
+}>;
+
+export declare type InstrumentPreset = Static<typeof InstrumentPresetSchema>;
+
+/**
+ * TypeBox schema for a song the audio module can play: instruments (Tone.js
+ * presets with an effects chain), tracks (one instrument or audio lane each)
+ * and clips placed on those tracks. All positions and lengths are in beats at
+ * the song's tempo; audio clips reference a URL the runtime can fetch.
+ *
+ * Creator's Music mode authors `.song.json` documents that strip down to this
+ * shape (`toRuntimeSong` in `@zylem-creator/shared`).
+ */
+export declare const InstrumentPresetSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"synth">, _sinclair_typebox.TLiteral<"polySynth">, _sinclair_typebox.TLiteral<"fmSynth">, _sinclair_typebox.TLiteral<"amSynth">, _sinclair_typebox.TLiteral<"membraneSynth">, _sinclair_typebox.TLiteral<"metalSynth">, _sinclair_typebox.TLiteral<"noiseSynth">, _sinclair_typebox.TLiteral<"pluckSynth">]>;
+
 /**
  * Intersect a ray with the plane through `origin` with the given normal.
  *
@@ -3898,6 +4840,9 @@ declare class InstanceManager {
  */
 export declare function intersectPlane(ray: GizmoRay, origin: Vector3, normal: Vector3, target: Vector3): Vector3 | null;
 
+/** True once `ensureAudio()` has successfully started the context. */
+export declare function isAudioReady(): boolean;
+
 /**
  * Check if a shader is a GLSL shader
  */
@@ -3909,6 +4854,44 @@ export declare function isManagedRenderEntity(entity: {
     isBundled?: boolean;
 }): boolean;
 
+/**
+ * Configuration for the isometric perspective.
+ * The offset is world-locked along (1, 1, 1): yaw 45°, elevation atan(√2).
+ */
+export declare interface IsometricOptions {
+    /** Distance from the target along the isometric axis. Default 10. */
+    distance?: number;
+    /** Orthographic frustum size. Default 10. */
+    zoom?: number;
+    /** Key in CameraContext.targets to frame. Default 'primary'. */
+    targetKey?: string;
+    /** Fallback camera position when no target exists. */
+    initialPosition?: Vec3Input;
+    /** Fallback lookAt point when no target exists. */
+    initialLookAt?: Vec3Input;
+}
+
+/**
+ * Orthographic isometric perspective.
+ *
+ * The view direction stays locked in world space, so the target can move
+ * without the camera orbiting around it. Player look input is not accepted.
+ */
+export declare class IsometricPerspective implements CameraPerspective {
+    readonly id = "isometric";
+    readonly projection: "orthographic";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    private initialPosition?;
+    private initialLookAt?;
+    constructor(options?: IsometricOptions);
+    getBasePose(ctx: CameraContext): CameraPose;
+    private staticPose;
+    private pose;
+}
+
 export declare function isPickMode(): boolean;
 
 declare interface IStage {
@@ -3933,6 +4916,11 @@ export declare function isTSLShader(shader: ZylemShader): shader is ZylemTSLShad
  */
 export declare function isWebGPUSupported(): Promise<boolean>;
 
+/** Items on every event/audio track with `time` in `(from, to]`, in time order. */
+export declare function itemsBetween<T extends {
+    time: number;
+}>(items: readonly T[], from: number, to: number): T[];
+
 /**
  * Stylized joystick base SVG: outer ring, subtle inner ring, and four
  * directional tabs. Designed to scale to any size; consumes only theme
@@ -3994,6 +4982,10 @@ export declare const KeyboardMappingSchema: _sinclair_typebox.TRecord<_sinclair_
 
 export { length_2 as length }
 
+export declare function lerpPose(a: EvaluatedPose, b: EvaluatedPose, t: number): EvaluatedPose;
+
+export declare function lerpVec3(a: Vec3Def, b: Vec3Def, t: number): Vec3Def;
+
 /**
  * Provides BaseNode-like lifecycle without ECS/children. Consumers implement
  * the protected hooks and may assign public setup/update/destroy callbacks.
@@ -4102,6 +5094,9 @@ export declare type LoadingEvent = {
     current?: number;
 };
 
+/** Loads Tone.js (once) without touching the AudioContext. */
+export declare function loadTone(): Promise<ToneModule>;
+
 /** Per-axis lock input: `true` locks all axes, or pass an [x, y, z] tuple. */
 declare type LockAxesInput = boolean | readonly [boolean, boolean, boolean];
 
@@ -4170,6 +5165,9 @@ declare interface MaterialOptions {
 
 export { max }
 
+/** The default selection view: the object's world AABB, padded. */
+export declare function measureObjectSelectionBounds(object: Object3D, target: Box3): Box3;
+
 /**
  * Deep-merges multiple GameInputConfig objects into one.
  * At the player level, configs are merged (both apply).
@@ -4190,6 +5188,12 @@ declare class MeshBuilder {
  */
 declare type MeshBuilderOptions = Partial<Pick<GameEntityOptions, 'material'>>;
 
+/** MIDI pitch to Hz with A4 = 440. */
+export declare function midiToFrequency(pitch: number): number;
+
+/** `60` → `C4`, the spelling Tone.js accepts as a note name. */
+export declare function midiToNoteName(pitch: number): string;
+
 export { min }
 
 export { mix }
@@ -4344,6 +5348,30 @@ export declare function normalizeVec2(input?: Vec2Input | null, defaults?: Vec2I
 
 export declare function normalizeVec3(input?: Vec3Input | null, defaults?: Vec3Input | Partial<Vec3Components>): Vec3Components;
 
+export declare type NoteClip = Static<typeof NoteClipSchema>;
+
+export declare const NoteClipSchema: _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"notes">;
+    id: _sinclair_typebox.TString;
+    trackId: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** Beats from the song start. */
+    start: _sinclair_typebox.TNumber;
+    /** Beats; notes past the end are not played. */
+    length: _sinclair_typebox.TNumber;
+    notes: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        /** MIDI pitch, 0–127. */
+        pitch: _sinclair_typebox.TInteger;
+        /** Beats from the clip start. */
+        start: _sinclair_typebox.TNumber;
+        /** Beats. */
+        duration: _sinclair_typebox.TNumber;
+        /** 0–1; defaults to 0.8. */
+        velocity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    }>>;
+}>;
+
 declare interface ObjectBounds {
     width: number;
     height: number;
@@ -4465,6 +5493,11 @@ export declare type OpacityEntity = {
     mesh?: Object3D | null;
 };
 
+declare type OscillatorType_2 = Static<typeof OscillatorTypeSchema>;
+export { OscillatorType_2 as OscillatorType }
+
+declare const OscillatorTypeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"sine">, _sinclair_typebox.TLiteral<"square">, _sinclair_typebox.TLiteral<"sawtooth">, _sinclair_typebox.TLiteral<"triangle">]>;
+
 /**
  * Pack a collision type + filter into the runtime's interaction-groups u32
  * (high 16 bits = membership mask, low 16 bits = filter mask).
@@ -4480,6 +5513,14 @@ declare interface PackKeyConfig {
     colorHex?: number;
 }
 
+/**
+ * Thicken any axis thinner than the minimum and add the uniform margin, in
+ * place. The minimum is proportional to the entity's largest extent so a
+ * 10-unit floor gets a visible slab while a coin-sized disk does not turn
+ * into a cube. Empty or non-finite boxes are returned untouched.
+ */
+export declare function padSelectionBounds(box: Box3): Box3;
+
 /**
  * Run all actions simultaneously. Done when all children are done.
  *
@@ -4528,15 +5569,27 @@ export { ParticlePresetMaterialOptions }
 
 export { particlePresets }
 
+/**
+ * Minimal WAV (RIFF, 16-bit PCM) encoder for rendered audio. Works on any
+ * `AudioBuffer`-shaped object so it can run without a Web Audio context.
+ */
+export declare interface PcmSource {
+    numberOfChannels: number;
+    sampleRate: number;
+    length: number;
+    getChannelData(channel: number): Float32Array;
+}
+
 /**
  * Perspective-specific options union.
  * Extend as new perspective types are added.
  */
-export declare type PerspectiveOptions = ThirdPersonOptions | Fixed2DOptions | FirstPersonOptions;
+export declare type PerspectiveOptions = ThirdPersonOptions | Fixed2DOptions | FirstPersonOptions | IsometricOptions | TopDownOptions | SecondPersonOptions;
 
 export declare const Perspectives: {
     readonly FirstPerson: "first-person";
     readonly ThirdPerson: "third-person";
+    readonly SecondPerson: "second-person";
     readonly Isometric: "isometric";
     readonly Flat2D: "flat-2d";
     readonly Fixed2D: "fixed-2d";
@@ -4642,6 +5695,15 @@ declare interface PlaneCollisionOptions extends BaseCollisionOptions {
 
 declare type PlaneOptions = BaseNode | Partial<ZylemPlaneOptions>;
 
+/** How one axis of the follow focus tracks the target. */
+export declare type PlatformAxisMode = 'delay' | 'settle' | 'off';
+
+export declare interface PlatformAxisModes {
+    x?: PlatformAxisMode;
+    y?: PlatformAxisMode;
+    z?: PlatformAxisMode;
+}
+
 export { Platformer2DBehavior }
 
 export { Platformer2DBehaviorOptions }
@@ -4686,6 +5748,45 @@ export { Platformer3DStateComponent }
 
 export { PlatformerCollisionContext }
 
+/**
+ * Options for the Super Mario World style follow.
+ *
+ * `delay` lerps toward the target and can wait inside a deadzone.
+ * `settle` holds still while the axis is moving (a jump, a lane change) and
+ * eases to the new rest once the axis goes quiet — landing on a platform.
+ * `off` leaves that axis of the incoming pose alone.
+ */
+export declare interface PlatformFollowOptions {
+    /** Key in CameraContext.targets to follow. Default 'primary'. */
+    targetKey?: string;
+    /**
+     * Per-axis mode. Default: x and z delay, y settles. Vertical jumps do not
+     * drag the camera; landing does. The same settle mode works on a horizontal axis.
+     */
+    axes?: PlatformAxisModes;
+    /**
+     * Interpolation factor for `delay` axes, in 0..1 per 60Hz frame.
+     * 1 = instant. Scaled by dt. Default 0.1.
+     */
+    lerpFactor?: number;
+    /**
+     * Deadzone in world units for `delay` axes. The focus holds until the
+     * target (plus lookahead) leaves this window. Default 0.
+     */
+    window?: number;
+    /** Speed, in units/second, at or below which a `settle` axis counts as resting. Default 0.75. */
+    settleSpeed?: number;
+    /** Seconds a `settle` axis must stay slow before the focus accepts the new rest. Default 0.15. */
+    settleTime?: number;
+    /** Interpolation factor used once a `settle` axis has a new rest. Default 0.08. */
+    settleLerp?: number;
+    /**
+     * World units of lookahead along the last travel direction.
+     * Applied on `delay` axes only. Default 0.
+     */
+    lookahead?: number;
+}
+
 export { PlayerInput }
 
 export declare interface PointLightOptions extends BaseLightOptions {
@@ -4720,6 +5821,9 @@ export { PrebakeWorkerRequest }
 
 export { PrebakeWorkerResponse }
 
+/** The shot that ended most recently before `shot` began, on any camera track. */
+export declare function previousShot(definition: CutsceneDefinition, shot: CameraShot): CameraShot | undefined;
+
 export declare const PYRAMID_TYPE: unique symbol;
 
 /**
@@ -4888,6 +5992,12 @@ declare class RendererManager {
      * replacement for the old `EffectComposer` + `RenderPass`.
      */
     setupPostProcessing(scene: Scene, camera: Camera): void;
+    /**
+     * Point an already-built post-processing pass at a replacement camera.
+     * No-ops when post-processing has not been set up; the next setup call
+     * receives whatever camera the stage passes in.
+     */
+    rebindPostProcessingCamera(camera: Camera): void;
     /** Whether a stage transition is currently in flight. */
     get transitionActive(): boolean;
     /**
@@ -4896,6 +6006,14 @@ declare class RendererManager {
      * its pipeline is set up. Call before tearing down the outgoing stage.
      */
     beginSnapshotTransition(resolved: ResolvedStageTransition, scene: Scene, camera: Camera): void;
+    /**
+     * Blend from the current picture into the frames that follow without
+     * changing stage: snapshot the outgoing frame, then rebuild the pipeline
+     * so the blend is composed immediately. Used by cutscene scene changes
+     * and any in-stage "cut" the game wants to soften. Move the camera right
+     * after calling this so the snapshot shows the outgoing shot.
+     */
+    beginInStageTransition(resolved: ResolvedStageTransition, scene: Scene, camera: Camera): void;
     /**
      * Complete the active transition immediately: rebuild the normal
      * pipeline, release transition resources, and fire `onComplete`.
@@ -4983,6 +6101,22 @@ declare class RendererManager {
     dispose(): void;
 }
 
+/**
+ * Renders a song (or a subset of its tracks) to an `AudioBuffer` offline,
+ * faster than real time. Pair with `encodeWav` to get a file. Works without
+ * a user gesture: offline contexts do not need to be resumed.
+ */
+export declare function renderSong(song: SongDefinition, options?: RenderSongOptions): Promise<AudioBuffer>;
+
+export declare interface RenderSongOptions {
+    /** Render only these tracks (mute/solo are ignored so a muted track can still be bounced). */
+    trackIds?: Iterable<string>;
+    sampleRate?: number;
+    /** Extra seconds after the song end so releases and reverb tails finish. */
+    tail?: number;
+    resolveUrl?: (url: string) => string;
+}
+
 /**
  * Routes entities to scene-direct (`none`), WebGPU bundles (`environment`), or
  * instanced meshes (`pack`) based on `options.category`.
@@ -5080,6 +6214,13 @@ export declare interface ResolveGameConfigRuntime {
 /** Resolve the render category for an entity. Defaults to `none`. */
 export declare function resolveRenderCategory(options?: RenderCategoryOptions | null): RenderCategory;
 
+/**
+ * The selection bounds for an entity: its own {@link SelectionBoundsProvider}
+ * answer when it has one, otherwise the padded AABB of `group ?? mesh`.
+ * Returns `null` when there is nothing to select, so callers need one check.
+ */
+export declare function resolveSelectionBounds(entity: unknown, target: Box3): Box3 | null;
+
 /**
  * Normalize a theme input to a fully populated {@link TouchTheme}.
  *
@@ -5359,6 +6500,12 @@ export { RuntimeTriggerRegion2DHandle }
 
 export { RuntimeTriggerRegion2DOptions }
 
+/** Evenly spaced samples of a dolly path, for drawing it. */
+export declare function sampleDollyPath(path: DollyPath, segments?: number): Vec3Def[];
+
+/** The scene containing `time` (last one wins on shared boundaries; the final scene past the end). */
+export declare function sceneAt(scenes: readonly CutsceneScene[], time: number): CutsceneScene | undefined;
+
 declare interface SceneState {
     backgroundColor: Color | string;
     backgroundImage: string | null;
@@ -5372,6 +6519,59 @@ declare interface SceneState {
     defaultLighting?: boolean;
 }
 
+export declare type SceneTransition = Static<typeof SceneTransitionSchema>;
+
+export declare const SceneTransitionSchema: _sinclair_typebox.TObject<{
+    type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"cut">, _sinclair_typebox.TLiteral<"fade">, _sinclair_typebox.TLiteral<"wipe">, _sinclair_typebox.TLiteral<"radial">, _sinclair_typebox.TLiteral<"noise">, _sinclair_typebox.TLiteral<"cells">]>;
+    /** Seconds; ignored for `cut`. */
+    duration: _sinclair_typebox.TNumber;
+    easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+}>;
+
+export declare type SceneTransitionType = Static<typeof SceneTransitionTypeSchema>;
+
+declare const SceneTransitionTypeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"cut">, _sinclair_typebox.TLiteral<"fade">, _sinclair_typebox.TLiteral<"wipe">, _sinclair_typebox.TLiteral<"radial">, _sinclair_typebox.TLiteral<"noise">, _sinclair_typebox.TLiteral<"cells">]>;
+
+export declare interface ScheduledAudio {
+    trackId: string;
+    clipId: string;
+    url: string;
+    /** Seconds from the song start. */
+    time: number;
+    /** Seconds into the file. */
+    offset: number;
+    /** Seconds. */
+    duration: number;
+    /** dB. */
+    gain: number;
+}
+
+export declare interface ScheduledNote {
+    trackId: string;
+    clipId: string;
+    instrumentId: string;
+    /** Seconds from the song start. */
+    time: number;
+    /** Seconds. */
+    duration: number;
+    pitch: number;
+    velocity: number;
+}
+
+export declare interface ScheduleOptions {
+    /** Only schedule these tracks (mute/solo are still honored). */
+    trackIds?: Iterable<string>;
+    /** Ignore mute/solo and schedule every listed track. */
+    ignoreMix?: boolean;
+}
+
+/**
+ * Flattens a song into absolute note and audio events in seconds. Notes are
+ * clipped to their clip's length and to the song end; audio clips are
+ * clipped to the song end.
+ */
+export declare function scheduleSong(song: SongDefinition, options?: ScheduleOptions): SongSchedule;
+
 /**
  * CooldownIcon -- a WoW-style cooldown icon UI entity.
  *
@@ -5447,6 +6647,72 @@ export { ScreenWrapOptions }
 
 export { ScreenWrapState }
 
+/**
+ * Configuration for the second-person perspective.
+ *
+ * The camera sits on another entity (`anchorKey`) and looks at the subject.
+ * Nothing here reads player look input.
+ */
+export declare interface SecondPersonOptions {
+    /** Key of the entity whose eyes the camera uses. Default 'anchor'. */
+    anchorKey?: string;
+    /** Key of the entity to look at. Default 'primary'. */
+    subjectKey?: string;
+    /** Height above the anchor's position. Default 1.7. */
+    eyeHeight?: number;
+    /** Perspective field of view. Default 75. */
+    fov?: number;
+    /** Fallback camera position when the anchor is missing. */
+    initialPosition?: Vec3Input;
+    /** Fallback lookAt point when the anchor is missing. */
+    initialLookAt?: Vec3Input;
+}
+
+/**
+ * Second-person perspective.
+ *
+ * Position comes from an anchor entity. The subject, when present, is the
+ * look-at; otherwise the camera looks along the anchor's forward (−Z).
+ * The player's facing does not move this camera.
+ */
+export declare class SecondPersonPerspective implements CameraPerspective {
+    readonly id = "second-person";
+    readonly projection: "perspective";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    private initialPosition?;
+    private initialLookAt?;
+    constructor(options?: SecondPersonOptions);
+    getBasePose(ctx: CameraContext): CameraPose;
+    private staticPose;
+    /** Anchor forward in world space. Three.js objects look down −Z. */
+    private anchorForward;
+}
+
+export declare function secondsToBeats(seconds: number, bpm: number): number;
+
+/** Uniform margin around the box, as a fraction of its largest extent. */
+export declare const SELECTION_BOUNDS_MARGIN = 0.02;
+
+/** A thin axis is padded up to this fraction of the largest extent... */
+export declare const SELECTION_THIN_AXIS_FRACTION = 0.05;
+
+export declare const SELECTION_THIN_AXIS_MAX = 1;
+
+/** ...clamped between these world-unit bounds. */
+export declare const SELECTION_THIN_AXIS_MIN = 0.1;
+
+/**
+ * Implemented by entities that define their own selection view. `target`
+ * is a scratch box to write into; return it, or `null` when the entity
+ * currently has no selectable volume. World space.
+ */
+export declare interface SelectionBoundsProvider {
+    getSelectionBounds(target: Box3): Box3 | null;
+}
+
 export { SemanticParticlePresetOptions }
 
 /**
@@ -5495,6 +6761,19 @@ export declare function setAddType(typeId: string | null, props?: Record<string,
  */
 export declare function setCameraFeed(entity: StageEntity, camera: CameraWrapper, options?: CameraFeedOptions): void;
 
+/**
+ * Registers the blend shaders every stage-bound cutscene uses for its scene
+ * transitions, typically once at startup:
+ *
+ * ```ts
+ * import { createStageTransition } from '@zylem/shaders';
+ * setCutsceneTransitionShaders((type) => createStageTransition({ pattern: type }).shader);
+ * ```
+ *
+ * Without this, every non-`cut` transition is a plain crossfade.
+ */
+export declare function setCutsceneTransitionShaders(resolver: ((type: SceneTransitionType) => ZylemTransitionShader | undefined) | null): void;
+
 export declare function setDebugTool(tool: DebugTools): void;
 
 /**
@@ -5644,6 +6923,17 @@ export declare function shortestAngleDelta(from: number, to: number): number;
 
 declare function shortHash(objString: string): string;
 
+/** The shot covering `time` on one track, if any (last one wins on overlaps). */
+export declare function shotAt(shots: readonly CameraShot[], time: number): CameraShot | undefined;
+
+export declare type ShotBlend = Static<typeof ShotBlendSchema>;
+
+declare const ShotBlendSchema: _sinclair_typebox.TObject<{
+    /** Seconds spent blending from the previous shot's camera; 0 is a hard cut. */
+    duration: _sinclair_typebox.TNumber;
+    easing: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"linear">, _sinclair_typebox.TLiteral<"easeIn">, _sinclair_typebox.TLiteral<"easeOut">, _sinclair_typebox.TLiteral<"easeInOut">]>;
+}>;
+
 export { Simulation }
 
 export declare class SimulationBody implements PhysicsRenderPoseProvider {
@@ -5794,6 +7084,238 @@ export declare function snapToIncrement(value: number, increment: number): numbe
 /** {@link snapToIncrement} across all three components. */
 export declare function snapVec3(value: Vec3, increment: number): Vec3;
 
+export declare type SongClip = Static<typeof SongClipSchema>;
+
+export declare const SongClipSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"notes">;
+    id: _sinclair_typebox.TString;
+    trackId: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** Beats from the song start. */
+    start: _sinclair_typebox.TNumber;
+    /** Beats; notes past the end are not played. */
+    length: _sinclair_typebox.TNumber;
+    notes: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        /** MIDI pitch, 0–127. */
+        pitch: _sinclair_typebox.TInteger;
+        /** Beats from the clip start. */
+        start: _sinclair_typebox.TNumber;
+        /** Beats. */
+        duration: _sinclair_typebox.TNumber;
+        /** 0–1; defaults to 0.8. */
+        velocity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    }>>;
+}>, _sinclair_typebox.TObject<{
+    kind: _sinclair_typebox.TLiteral<"audio">;
+    id: _sinclair_typebox.TString;
+    trackId: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** URL of the audio file. */
+    url: _sinclair_typebox.TString;
+    /** Beats from the song start. */
+    start: _sinclair_typebox.TNumber;
+    /** Seconds trimmed from the start of the file. */
+    offset: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    /** Beats. */
+    length: _sinclair_typebox.TNumber;
+    /** Clip gain in dB. */
+    gain: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+}>]>;
+
+export declare type SongDefinition = Static<typeof SongDefinitionSchema>;
+
+export declare const SongDefinitionSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    bpm: _sinclair_typebox.TNumber;
+    timeSignature: _sinclair_typebox.TObject<{
+        numerator: _sinclair_typebox.TInteger;
+        denominator: _sinclair_typebox.TInteger;
+    }>;
+    lengthBars: _sinclair_typebox.TInteger;
+    loop: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+        enabled: _sinclair_typebox.TBoolean;
+        /** Beats. */
+        start: _sinclair_typebox.TNumber;
+        end: _sinclair_typebox.TNumber;
+    }>>;
+    instruments: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        preset: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"synth">, _sinclair_typebox.TLiteral<"polySynth">, _sinclair_typebox.TLiteral<"fmSynth">, _sinclair_typebox.TLiteral<"amSynth">, _sinclair_typebox.TLiteral<"membraneSynth">, _sinclair_typebox.TLiteral<"metalSynth">, _sinclair_typebox.TLiteral<"noiseSynth">, _sinclair_typebox.TLiteral<"pluckSynth">]>;
+        oscillator: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"sine">, _sinclair_typebox.TLiteral<"square">, _sinclair_typebox.TLiteral<"sawtooth">, _sinclair_typebox.TLiteral<"triangle">]>>;
+        envelope: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+            attack: _sinclair_typebox.TNumber;
+            decay: _sinclair_typebox.TNumber;
+            sustain: _sinclair_typebox.TNumber;
+            release: _sinclair_typebox.TNumber;
+        }>>;
+        /** Output trim in dB. */
+        volume: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        effects: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TString;
+            type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"reverb">, _sinclair_typebox.TLiteral<"delay">, _sinclair_typebox.TLiteral<"distortion">, _sinclair_typebox.TLiteral<"filter">]>;
+            /** Dry/wet mix, 0–1. */
+            wet: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            /** Effect-specific settings forwarded to the Tone.js constructor. */
+            options: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnion<[_sinclair_typebox.TNumber, _sinclair_typebox.TString, _sinclair_typebox.TBoolean]>>>;
+        }>>>;
+    }>>;
+    tracks: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+        id: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TString;
+        kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"instrument">, _sinclair_typebox.TLiteral<"audio">]>;
+        instrumentId: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        color: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        /** Fader in dB. */
+        volume: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        /** -1 (left) … 1 (right). */
+        pan: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        mute: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        solo: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+    }>>;
+    clips: _sinclair_typebox.TArray<_sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+        kind: _sinclair_typebox.TLiteral<"notes">;
+        id: _sinclair_typebox.TString;
+        trackId: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        /** Beats from the song start. */
+        start: _sinclair_typebox.TNumber;
+        /** Beats; notes past the end are not played. */
+        length: _sinclair_typebox.TNumber;
+        notes: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            /** MIDI pitch, 0–127. */
+            pitch: _sinclair_typebox.TInteger;
+            /** Beats from the clip start. */
+            start: _sinclair_typebox.TNumber;
+            /** Beats. */
+            duration: _sinclair_typebox.TNumber;
+            /** 0–1; defaults to 0.8. */
+            velocity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        }>>;
+    }>, _sinclair_typebox.TObject<{
+        kind: _sinclair_typebox.TLiteral<"audio">;
+        id: _sinclair_typebox.TString;
+        trackId: _sinclair_typebox.TString;
+        name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        /** URL of the audio file. */
+        url: _sinclair_typebox.TString;
+        /** Beats from the song start. */
+        start: _sinclair_typebox.TNumber;
+        /** Seconds trimmed from the start of the file. */
+        offset: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        /** Beats. */
+        length: _sinclair_typebox.TNumber;
+        /** Clip gain in dB. */
+        gain: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    }>]>>;
+    /** Master fader in dB. */
+    masterVolume: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+}>;
+
+export declare function songLengthBeats(song: Pick<SongDefinition, 'lengthBars' | 'timeSignature'>): number;
+
+export declare function songLengthSeconds(song: Pick<SongDefinition, 'lengthBars' | 'timeSignature' | 'bpm'>): number;
+
+export declare type SongLoop = Static<typeof SongLoopSchema>;
+
+export declare const SongLoopSchema: _sinclair_typebox.TObject<{
+    enabled: _sinclair_typebox.TBoolean;
+    /** Beats. */
+    start: _sinclair_typebox.TNumber;
+    end: _sinclair_typebox.TNumber;
+}>;
+
+export declare type SongNote = Static<typeof SongNoteSchema>;
+
+export declare const SongNoteSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** MIDI pitch, 0–127. */
+    pitch: _sinclair_typebox.TInteger;
+    /** Beats from the clip start. */
+    start: _sinclair_typebox.TNumber;
+    /** Beats. */
+    duration: _sinclair_typebox.TNumber;
+    /** 0–1; defaults to 0.8. */
+    velocity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+}>;
+
+export declare interface SongPlayer {
+    readonly definition: SongDefinition;
+    readonly state: SongPlayerState;
+    /** Resolves once Tone.js and every audio clip are loaded. */
+    readonly ready: Promise<void>;
+    /** Starts (or resumes) playback; needs a prior user gesture the first time. */
+    play(fromBeat?: number): Promise<void>;
+    pause(): void;
+    /** Stops and rewinds to the start. */
+    stop(): void;
+    seek(beat: number): void;
+    /** Playhead in beats. */
+    position(): number;
+    /** Playhead in seconds at the current tempo. */
+    seconds(): number;
+    setBpm(bpm: number): void;
+    setLoop(loop: SongLoop | null): void;
+    setTrackMute(trackId: string, mute: boolean): void;
+    setTrackSolo(trackId: string, solo: boolean): void;
+    /** dB. */
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackPan(trackId: string, pan: number): void;
+    /** dB. */
+    setMasterVolume(volume: number): void;
+    /** Plays one note on a track's instrument right now (for auditioning). */
+    preview(trackId: string, pitch: number, duration?: number, velocity?: number): Promise<void>;
+    /** Swaps in a new definition, keeping the playhead and state. */
+    update(definition: SongDefinition): Promise<void>;
+    on<K extends keyof SongPlayerEvents>(event: K, handler: SongPlayerEvents[K]): () => void;
+    dispose(): void;
+}
+
+export declare interface SongPlayerEvents {
+    /** Fires at the start of every bar with the 0-based bar index. */
+    bar: (bar: number) => void;
+    /** Fires at the start of every beat with the 0-based beat index. */
+    beat: (beat: number) => void;
+    /** Fires when a non-looping song reaches its end. */
+    complete: () => void;
+    state: (state: SongPlayerState) => void;
+}
+
+export declare interface SongPlayerOptions {
+    /** Resolve clip URLs (for example, relative asset paths) before loading. */
+    resolveUrl?: (url: string) => string;
+    /** Route the master output here instead of the speakers. */
+    destination?: ToneNs.InputNode;
+}
+
+export declare type SongPlayerState = 'stopped' | 'playing' | 'paused';
+
+export declare interface SongSchedule {
+    notes: ScheduledNote[];
+    audio: ScheduledAudio[];
+    /** Seconds. */
+    length: number;
+}
+
+export declare type SongTrack = Static<typeof SongTrackSchema>;
+
+export declare const SongTrackSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    name: _sinclair_typebox.TString;
+    kind: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"instrument">, _sinclair_typebox.TLiteral<"audio">]>;
+    instrumentId: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    color: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    /** Fader in dB. */
+    volume: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    /** -1 (left) … 1 (right). */
+    pan: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    mute: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+    solo: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+}>;
+
 export declare const SPHERE_TYPE: unique symbol;
 
 /**
@@ -6044,6 +7566,19 @@ export declare type StageConfigLike = Partial<{
 
 export { StageConfigPayload }
 
+export declare interface StageCutsceneHostOptions {
+    /**
+     * Looks a song reference (slug or URL from a `playSong` event / audio
+     * item) up to a definition the audio module can play. Without it song
+     * items are ignored.
+     */
+    resolveSong?: (ref: string) => SongDefinition | Promise<SongDefinition | undefined> | undefined;
+    /** Maps a transition type to a blend shader; defaults to a crossfade for every type. */
+    transitionShader?: (type: SceneTransitionType) => ZylemTransitionShader | undefined;
+    /** Called for `emit` events in addition to the stage dispatch. */
+    onEvent?: (name: string, payload: Record<string, unknown>) => void;
+}
+
 /**
  * Self-managing debug delegate that subscribes to `debugState` internally.
  *
@@ -6069,6 +7604,10 @@ declare class StageDebugDelegate {
     private warnedMissingAddFactory;
     private transformTool;
     private swatchApplier;
+    private marquee;
+    private selectionHighlight;
+    private selectionBoundsPool;
+    private hoverBounds;
     private grid;
     private lastTool;
     /** Element the current gizmo drag captured, so pointerup is never missed. */
@@ -6082,6 +7621,13 @@ declare class StageDebugDelegate {
     /** Camera used for debug orbit / raycasts (active primary, usually `__debug__`). */
     private getDebugViewCamera;
     private resolveEntity;
+    /**
+     * Every entity a marquee may catch. `childrenMap` is the live stage;
+     * `debugMap` is consulted too so anything only registered there (the same
+     * set the single pick resolves through) is not skipped. Whether an entity
+     * has a selectable volume is the marquee's call, via its selection bounds.
+     */
+    private forEachSelectableEntity;
     /** Copy all stage children into debugMap so raycast/select tools work after enabling debug mid-session. */
     private populateDebugMap;
     private ensureCameraDebugDelegate;
@@ -6114,6 +7660,12 @@ declare class StageDebugDelegate {
      * available when a tool is armed with debug off.
      */
     private ensureToolVisuals;
+    /**
+     * Outline every selected entity. Re-fitted each frame so the boxes follow
+     * entities that move, and so a uuid whose entity has gone (deleted, or
+     * undone) simply drops out instead of leaving a stale box behind.
+     */
+    private updateSelectionHighlight;
     /**
      * Hide the overlays whose tool has just gone away.
      *
@@ -6744,6 +8296,55 @@ export declare const standardShader: {
 
 export { step }
 
+export declare interface StrategyPanBehavior extends CameraBehavior {
+    /** Follow `key`, or pass null to pan freely. Clears a manual-pan suspension. */
+    setFollowKey(key: string | null): void;
+}
+
+/** What {@link StrategyPanOptions.sampleInput} returns each frame. */
+export declare interface StrategyPanInput {
+    pointer?: StrategyPointer;
+    /** Stick or arrow intent, −1..1. +x is screen right, +y is screen up. */
+    pan?: {
+        x: number;
+        y: number;
+    };
+}
+
+export declare interface StrategyPanOptions {
+    /**
+     * Read pointer and pan intent. Kept as a closure so the behavior does not
+     * import InputManager. Typical source: `inputs.p1.pointer` and directions.
+     */
+    sampleInput?: () => StrategyPanInput;
+    /** Fraction of the viewport that counts as an edge. Default 0.08. */
+    edgeMargin?: number;
+    /** World units per second at a flush edge. Default 12. */
+    edgeSpeed?: number;
+    /** World units per second at full stick deflection. Default 16. */
+    panSpeed?: number;
+    /** Target key to ease toward. Null follows nothing. */
+    followKey?: string | null;
+    /** Interpolation factor while following, per 60Hz frame. Default 0.12. */
+    followLerp?: number;
+    /**
+     * A manual pan or edge scroll drops follow until {@link StrategyPanBehavior.setFollowKey}.
+     * Default true.
+     */
+    breakFollowOnPan?: boolean;
+}
+
+/**
+ * Pointer for edge scrolling.
+ * `x`/`y` are 0..1 from the top-left, unless `centered` is set, in which case
+ * they are −1..1 with −1 at the left and top (the shape of `inputs.p1.pointer.centerX/Y`).
+ */
+export declare interface StrategyPointer {
+    x: number;
+    y: number;
+    centered?: boolean;
+}
+
 export { SwatchApplyFailureReason }
 
 /** What a host reports back from a swatch batch. */
@@ -6780,6 +8381,9 @@ export { SwatchKind }
 
 export { SwatchSpec }
 
+/** Positions of named entities the cameras may reference, by name. */
+export declare type TargetLookup = (name: string) => Vec3Def | undefined;
+
 /**
  * Factory interface for generating entity copies
  */
@@ -6857,6 +8461,7 @@ export declare interface ThirdPersonOptions {
  */
 export declare class ThirdPersonPerspective implements CameraPerspective {
     readonly id = "third-person";
+    readonly projection: "perspective";
     /**
      * Slightly looser than the previous 0.15 to compose better with the
      * trailing-delay follow: the trail absorbs short, fast moves and the
@@ -7053,6 +8658,20 @@ declare class Timer {
     update(timestamp?: number): Timer;
 }
 
+export declare type TimeSignature = Static<typeof TimeSignatureSchema>;
+
+export declare const TimeSignatureSchema: _sinclair_typebox.TObject<{
+    numerator: _sinclair_typebox.TInteger;
+    denominator: _sinclair_typebox.TInteger;
+}>;
+
+/**
+ * Tone.js is loaded on demand so games without music never download it, and
+ * so the AudioContext is only started after a user gesture (browsers refuse
+ * to start one otherwise).
+ */
+export declare type ToneModule = typeof ToneNs;
+
 export { TopDownMovementBehavior }
 
 export { TopDownMovementBehaviorOptions }
@@ -7067,6 +8686,44 @@ export { TopDownMovementInputComponent }
 
 export { TopDownMovementStateComponent }
 
+/**
+ * Configuration for the top-down perspective.
+ * The camera sits above the target and looks straight down at the XZ plane.
+ */
+export declare interface TopDownOptions {
+    /** Height above the target, in world units. Default 10. */
+    height?: number;
+    /** Orthographic frustum size. Default 10. */
+    zoom?: number;
+    /** Key in CameraContext.targets to frame. Default 'primary'. */
+    targetKey?: string;
+    /** Fallback camera position when no target exists. */
+    initialPosition?: Vec3Input;
+    /** Fallback lookAt point when no target exists. */
+    initialLookAt?: Vec3Input;
+}
+
+/**
+ * Orthographic top-down perspective.
+ *
+ * Rotation is locked to world -Y. The camera follows the target's XZ and
+ * stays `height` above it. Player look input is not accepted.
+ */
+export declare class TopDownPerspective implements CameraPerspective {
+    readonly id = "top-down";
+    readonly projection: "orthographic";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    private initialPosition?;
+    private initialLookAt?;
+    constructor(options?: TopDownOptions);
+    getBasePose(ctx: CameraContext): CameraPose;
+    private staticPose;
+    private pose;
+}
+
 export { TopDownShooterCoordinator }
 
 export { TopDownShooterEntity }
@@ -7455,6 +9112,8 @@ export declare type Vec3Components = {
 /** Gravity as `[x, y, z]` components (JSON-serializable). */
 export declare const Vec3ComponentsSchema: _sinclair_typebox.TTuple<[_sinclair_typebox.TNumber, _sinclair_typebox.TNumber, _sinclair_typebox.TNumber]>;
 
+export declare type Vec3Def = Static<typeof Vec3Schema>;
+
 export declare type Vec3Input = Vec3 | {
     x?: number;
     y?: number;
@@ -7463,6 +9122,21 @@ export declare type Vec3Input = Vec3 | {
 
 export { Vec3Like }
 
+/**
+ * TypeBox schema for a cutscene the cinematics module can play: a timeline in
+ * seconds split into scenes, cameras (static, dolly along a spline, or
+ * following an entity) placed on camera tracks as shots, camera keyframes,
+ * and event/audio tracks that fire gameplay hooks at points in time.
+ *
+ * Creator's Director mode authors `.cutscene.json` documents that strip down
+ * to this shape (`toRuntimeCutscene` in `@zylem-creator/shared`).
+ */
+declare const Vec3Schema: _sinclair_typebox.TObject<{
+    x: _sinclair_typebox.TNumber;
+    y: _sinclair_typebox.TNumber;
+    z: _sinclair_typebox.TNumber;
+}>;
+
 declare type Vec3Tuple = readonly [number?, number?, number?] & {
     x?: number;
     y?: number;
@@ -8135,10 +9809,19 @@ declare class ZylemCamera {
      * Apply the final pipeline pose to the Three.js camera.
      */
     private commitPose;
+    /**
+     * Install a perspective and replace the Three.js camera when its projection
+     * kind differs from the live one. Pose is copied across; orbit controls and
+     * post-processing are rebound to the new instance.
+     */
+    applyPerspective(type: PerspectiveType, perspective: CameraPerspective): void;
+    private ensureProjection;
     /**
      * Create a Three.js camera based on perspective type.
      */
     private createCameraForPerspective;
+    private createPerspectiveCamera;
+    private createOrthographicCamera;
 }
 
 /**
@@ -8433,6 +10116,8 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     private lastPublishedGameConfig;
     /** Editor ↔ game bridge adapter (RAF-coalesced publishes, command intake). */
     private gameBridge;
+    /** Director mode's in-game cutscene preview, driven over the bridge. */
+    private cutscenePreview;
     /** Stops republishing the entity catalog on registry changes. */
     private catalogUnsubscribe;
     private readonly gameUpdateParams;
@@ -8671,10 +10356,12 @@ export declare type ZylemLineOptions = GameEntityOptions & {
     pickThreshold?: number;
 };
 
-export declare class ZylemParticleSystem extends GameEntity<ZylemParticleSystemOptions> {
+export declare class ZylemParticleSystem extends GameEntity<ZylemParticleSystemOptions> implements SelectionBoundsProvider {
     static type: symbol;
     __zylemParticleSystemEntity: true;
     private particleHandle;
+    /** The emitter's `group` is empty, so measuring it yields nothing; see {@link PARTICLE_SYSTEM_SELECTION_EXTENT}. */
+    getSelectionBounds(target: Box3): Box3 | null;
     constructor(options?: Partial<ZylemParticleSystemOptions>, initializeBehavior?: boolean);
     private bindStandaloneTransforms;
     private resolveParticleHandle;
@@ -9315,12 +11002,18 @@ declare class ZylemWorld implements Entity<ZylemWorld> {
     private clearEntityPhysicsState;
 }
 
-export declare class ZylemZone extends GameEntity<ZylemZoneOptions> implements CollisionHandlerDelegate {
+export declare class ZylemZone extends GameEntity<ZylemZoneOptions> implements CollisionHandlerDelegate, SelectionBoundsProvider {
     static type: symbol;
     private _enteredZone;
     private _exitedZone;
     private _zoneEntities;
     constructor(options?: ZylemZoneOptions);
+    /**
+     * A zone has no render object, so the editor cannot measure it. Its
+     * selection view is the sensor volume itself: `options.size` centred on
+     * the live pose (or the configured position before spawn).
+     */
+    getSelectionBounds(target: Box3): Box3 | null;
     handlePostCollision({ delta }: {
         delta: number;
     }): boolean;