@zylem/game-lib 0.8.8 → 0.9.0

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

@@ -1,5 +1,6 @@
 import { abs } from 'three/tsl';
 import { announceBridgeReady } from '@zylem/bridge';
+import { applySwatchesToSelection } from '@zylem/bridge';
 import { asin } from 'three/tsl';
 import { atan } from 'three/tsl';
 import { BehaviorDescriptor } from '@zylem/behaviors';
@@ -21,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';
@@ -28,11 +30,13 @@ import { BridgeHandler } from '@zylem/bridge';
 import { GameLoadingPayload as BridgeLoadingPayload } from '@zylem/bridge';
 import { BridgeMessages } from '@zylem/bridge';
 import { BridgeMessageType } from '@zylem/bridge';
+import { BridgeNdc } from '@zylem/bridge';
 import { BridgePose } from '@zylem/bridge';
 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';
@@ -70,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';
@@ -88,7 +96,10 @@ import { emitRuntimeTriggerRegionEnter } from '@zylem/behaviors/runtime-2d';
 import { EntityApplySwatchPayload } from '@zylem/bridge';
 import { EntityDefinition } from '@zylem/behaviors/core';
 import { EntityHandle } from '@zylem/behaviors/core';
+import { EntityPickPayload } from '@zylem/bridge';
+import { EntityPickResultPayload } from '@zylem/bridge';
 import { EntitySummaryPayload } from '@zylem/bridge';
+import { EntitySwatchAppliedPayload } from '@zylem/bridge';
 import { EntityThumbnailPayload } from '@zylem/bridge';
 import { EntityTypeDescriptor } from '@zylem/bridge';
 import { exp } from 'three/tsl';
@@ -276,6 +287,7 @@ import { RuntimeTriggerRegion2DEvent } from '@zylem/behaviors/runtime-2d';
 import { RuntimeTriggerRegion2DHandle } from '@zylem/behaviors/runtime-2d';
 import { RuntimeTriggerRegion2DOptions } from '@zylem/behaviors/runtime-2d';
 import { Scene } from 'three';
+import { SceneOperationEntry } from '@zylem/bridge';
 import { SceneOperationPayload } from '@zylem/bridge';
 import { ScreenVisibilityBehavior } from '@zylem/behaviors';
 import { ScreenVisibilityChangeContext } from '@zylem/behaviors';
@@ -336,6 +348,10 @@ import { StageSnapshotPayload } from '@zylem/bridge';
 import { StageTopDownPlane } from '@zylem/behaviors/core';
 import { Static } from '@sinclair/typebox';
 import { step } from 'three/tsl';
+import { SwatchApplyFailureReason } from '@zylem/bridge';
+import { SwatchApplyResult } from '@zylem/bridge';
+import { SwatchKind } from '@zylem/bridge';
+import { SwatchSpec } from '@zylem/bridge';
 import { Texture } from 'three';
 import * as three from 'three';
 import { ThrusterBehavior } from '@zylem/behaviors';
@@ -350,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';
@@ -421,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;
@@ -471,6 +494,8 @@ export { announceBridgeReady }
 
 declare type AnyNode = NodeLike | Promise<NodeLike>;
 
+export { applySwatchesToSelection }
+
 /**
  * Apply accumulated transformations from the store to the physics body.
  *
@@ -533,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;
@@ -662,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 }
@@ -724,6 +815,8 @@ export { BridgeMessages }
 
 export { BridgeMessageType }
 
+export { BridgeNdc }
+
 export { BridgeVec3 }
 
 /** Cuboid collider sized as `size.xyz` (full extents — half-extents are computed). */
@@ -836,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.
  *
@@ -1122,6 +1236,59 @@ 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 }
+
+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,
@@ -1225,6 +1392,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.
  *
@@ -1481,6 +1651,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
@@ -1585,6 +1768,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 }
@@ -1667,6 +1856,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;
@@ -1676,6 +1872,8 @@ export declare function createSprite(...args: Array<SpriteOptions>): ZylemSprite
  */
 export declare function createStage(...options: StageOptions): Stage;
 
+export declare function createStageCutsceneHost(stageLike: CutsceneStageLike, options?: StageCutsceneHostOptions): CutsceneHost;
+
 export declare function createText(...args: Array<TextOptions>): ZylemText;
 
 export { createThrusterInputComponent }
@@ -1707,6 +1905,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;
 
 /**
@@ -1741,6 +2442,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;
 
@@ -1931,16 +2634,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;
@@ -2104,6 +2848,10 @@ declare abstract class EntityMeshBuilder extends MeshBuilder {
     postBuild(): void;
 }
 
+export { EntityPickPayload }
+
+export { EntityPickResultPayload }
+
 /**
  * Runtime entity blueprint (open `data` for factory spreading).
  * Prefer {@link EntityJsonSchema} for editor / Monaco JSON Schema.
@@ -2134,6 +2882,8 @@ export declare function entitySpawner(factory: (x: number, y: number) => Promise
 
 export { EntitySummaryPayload }
 
+export { EntitySwatchAppliedPayload }
+
 /**
  * Generates and caches entity thumbnail previews for the editor entity list.
  * Renders a cloned Object3D into an offscreen RenderTarget on the shared WebGPU renderer.
@@ -2218,9 +2968,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.
@@ -2256,6 +3035,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 }
@@ -2474,6 +3320,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>;
@@ -2615,7 +3463,20 @@ 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.
+     *
+     * Order matters for the consumer: selection changes first (so a following
+     * `entity:selection` describes the new targets), then the undo record, then
+     * the ack — a consumer that persists on `ok` sees the operation already on
+     * the stack.
+     */
+    private handleApplySwatch;
     /**
      * Publish only the parts of `debugState` the editor does not already know.
      * Values that arrived as editor commands are recorded on `editorKnown`
@@ -2708,8 +3569,30 @@ export declare interface GameBridgeHost {
     createEntity?(typeId: string, props: Record<string, unknown> | undefined, pose: BridgePose | undefined): void;
     /** Undo or redo a committed scene operation (`scene:operation:apply`). */
     applySceneOperation?(op: SceneOperationPayload, direction: 'undo' | 'redo'): void;
-    /** Attach a catalog shader or behavior to a live entity (`entity:apply-swatch`). */
-    applySwatch?(payload: EntityApplySwatchPayload): void;
+    /**
+     * Raycast at normalized device coordinates and describe the entity hit
+     * (`entity:pick`). Hover should follow the pick only while pick mode is on.
+     */
+    pickEntity?(ndc: BridgeNdc): EntitySummaryPayload | null;
+    /**
+     * Apply every swatch to every uuid (`entity:apply-swatch`). Must report one
+     * result per uuid × swatch pair and return a `scene:operation` entry for
+     * each success so the batch is undoable as a single step.
+     */
+    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;
 }
 
 /**
@@ -3164,6 +4047,30 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
      * Used by the stage to auto-register required systems.
      */
     getBehaviorRefs(): BehaviorRef_2[];
+    /**
+     * Find the attached ref for a behavior, matched by descriptor key so a
+     * re-imported copy of the same descriptor still resolves.
+     */
+    getBehaviorRef<O extends Record<string, any>>(descriptor: BehaviorDescriptor_2<O, any>): BehaviorRef_2<O> | null;
+    hasBehavior(descriptor: BehaviorDescriptor_2<any, any>): boolean;
+    /**
+     * Detach a behavior from this entity.
+     *
+     * Removes the ref so future spawns skip it. If the entity is live in a
+     * stage, the stage must also drop the system link (see
+     * `StageEntityDelegate.detachBehaviorLink`); `StageDebugDelegate` does this
+     * for editor-driven removals.
+     *
+     * @param target The descriptor (matched by key) or the exact ref to remove.
+     * @returns The removed ref, or `null` when nothing matched.
+     */
+    removeBehavior(target: BehaviorDescriptor_2<any, any> | BehaviorRef_2<any>): BehaviorRef_2<any> | null;
+    /**
+     * Re-attach a previously removed ref as-is (options, FSM state and all).
+     * Used by undo so a restored behavior is the same object, not a re-created
+     * one.
+     */
+    restoreBehaviorRef(ref: BehaviorRef_2<any>): void;
     getCollisionCallbacks(): Array<(params: CollisionContext<this, O>) => void>;
     getCollisionRegistrations(): Array<CollisionRegistration<this, O>>;
     private copyBehaviorRefsTo;
@@ -3194,6 +4101,36 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
      */
     protected _cleanup(_params: CleanupContext<this>): void;
     _collision(other: GameEntity<O>, globals?: any, dispatch?: CollisionDispatchMetadata): void;
+    /**
+     * Whether this entity renders a mesh that a material can be assigned to.
+     * Lights, zones, and other mesh-less entities return `false`.
+     */
+    hasMaterial(): boolean;
+    /** The materials currently driving this entity's meshes. */
+    getMaterials(): Material[];
+    /**
+     * Rebuild this entity's material from creation-style options and swap it in
+     * on the live mesh, so a runtime change (an editor applying a shader swatch)
+     * renders exactly like a restart with `material: options` would.
+     *
+     * @param options Same shape as `GameEntityOptions.material`.
+     * @param settings `disposePrevious` (default `true`) frees the replaced
+     *   materials; pass `false` when keeping them for undo.
+     * @returns The replaced materials, or `null` when the entity has no mesh.
+     */
+    setMaterial(options: Partial<MaterialOptions>, settings?: {
+        disposePrevious?: boolean;
+    }): Material[] | null;
+    /**
+     * Assign already-built materials to every mesh this entity renders. Meshes
+     * that carried a material array keep the array shape, cycling through the
+     * supplied list so multi-material geometry stays fully covered.
+     *
+     * @returns The replaced materials, or `null` when the entity has no mesh.
+     */
+    replaceMaterials(materials: Material[], settings?: {
+        disposePrevious?: boolean;
+    }): Material[] | null;
     protected updateMaterials(params: any): void;
     buildInfo(): Record<string, string>;
     /**
@@ -3496,6 +4433,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 }
@@ -3796,6 +4736,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.
  *
@@ -3804,6 +4808,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
  */
@@ -3839,6 +4846,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
@@ -3900,6 +4912,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.
@@ -4008,6 +5024,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];
 
@@ -4076,6 +5095,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).
@@ -4096,6 +5118,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 }
@@ -4250,6 +5278,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;
@@ -4371,6 +5423,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).
@@ -4386,6 +5443,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.
  *
@@ -4434,6 +5499,17 @@ 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.
@@ -4626,6 +5702,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;
 
 /**
@@ -4802,6 +5881,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`.
@@ -4889,6 +5976,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`.
@@ -4986,6 +6089,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}.
  *
@@ -5265,6 +6375,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;
@@ -5278,6 +6394,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.
  *
@@ -5353,6 +6522,28 @@ export { ScreenWrapOptions }
 
 export { ScreenWrapState }
 
+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 }
 
 /**
@@ -5401,6 +6592,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;
 
 /**
@@ -5550,6 +6754,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 {
@@ -5700,6 +6915,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;
 
 /**
@@ -5950,6 +7397,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.
  *
@@ -5974,6 +7434,11 @@ declare class StageDebugDelegate {
     private lastDebugEnabled;
     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. */
@@ -5987,6 +7452,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;
@@ -6019,6 +7491,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.
      *
@@ -6032,13 +7510,27 @@ declare class StageDebugDelegate {
     update(): void;
     /**
      * Raycast at NDC coordinates (from a host that cannot send DOM pointer
-     * events, e.g. an overlay sitting on a preview iframe). Updates hover so
-     * the next `update()` paints the highlight.
+     * events, e.g. an overlay sitting on a preview iframe, or the bridge's
+     * `entity:pick`).
+     *
+     * Hover follows the pick only while pick mode is armed (a drag in flight),
+     * so a one-shot pick from an inspector does not disturb the user's hover.
+     * While armed, the next `update()` paints the highlight.
      */
-    pickAtNdc(ndcX: number, ndcY: number): {
+    pickAtNdc(ndcX: number, ndcY: number, options?: {
+        updateHover?: boolean;
+    }): {
         uuid: string;
         name: string;
     } | null;
+    /**
+     * Apply swatches to live entities (`entity:apply-swatch`). Every uuid ×
+     * swatch pair is attempted and reported; successful pairs are recorded so
+     * the operation can be undone exactly via {@link applySceneOperation}.
+     */
+    applySwatches(payload: EntityApplySwatchPayload & {
+        opId: string;
+    }): SwatchApplyOutcome_2;
     /** Collider wireframes, straight from the wasm simulation. */
     private updateColliderWireframes;
     /**
@@ -6286,11 +7778,35 @@ declare class StageEntityDelegate {
      */
     destroyAll(): void;
     private registerBehaviorLinks;
+    /**
+     * Index one ref, lazily create its system, and attach. Shared by spawn-time
+     * registration and late per-ref attaches.
+     */
+    private linkBehaviorRef;
+    private unlinkBehaviorLink;
     /**
      * Re-index an entity's behavior refs after a late `entity.use(...)`.
      * Spawn-time registration only sees refs that existed at attach.
+     *
+     * Detaches and re-attaches every behavior on the entity, which resets their
+     * per-link state. Prefer {@link attachBehaviorLink} /
+     * {@link detachBehaviorLink} when only one ref changed.
      */
     syncBehaviorLinks(entity: any): void;
+    /**
+     * Attach a single ref that was added to a live entity (`entity.use(...)`
+     * after spawn) without disturbing the entity's other behaviors.
+     *
+     * @returns `false` when the stage is not loaded or the ref is already linked.
+     */
+    attachBehaviorLink(entity: any, ref: BehaviorRef_2): boolean;
+    /**
+     * Detach a single ref's system link from a live entity, leaving its other
+     * behaviors attached.
+     *
+     * @returns `false` when no link for that ref exists.
+     */
+    detachBehaviorLink(entity: any, ref: BehaviorRef_2): boolean;
     private unregisterBehaviorLinks;
 }
 
@@ -6611,6 +8127,45 @@ export declare const standardShader: {
 
 export { step }
 
+export { SwatchApplyFailureReason }
+
+/** What a host reports back from a swatch batch. */
+export declare interface SwatchApplyOutcome {
+    results: SwatchApplyResult[];
+    entries: SceneOperationEntry[];
+}
+
+/**
+ * Applies swatches (configured shaders / behaviors) to live entities and
+ * inverts those applications for undo.
+ *
+ * One `entity:apply-swatch` message is a batch: every swatch is applied to
+ * every uuid, in order, under a single operation id. Each pair reports its own
+ * result so a multi-select apply can partially succeed (a light in the
+ * selection has no material) while the rest still land.
+ *
+ * Undo follows the stage's "editor holds the history, game holds the
+ * instances" rule. The original material and any displaced behavior refs are
+ * kept here per operation, so undo puts back the exact objects rather than a
+ * reconstruction — the pre-swatch material (texture, tint, standard shader) is
+ * usually not describable as a swatch at all.
+ */
+
+declare interface SwatchApplyOutcome_2 {
+    results: SwatchApplyResult[];
+    /** One entry per successful pair, ready for a `scene:operation`. */
+    entries: SceneOperationEntry[];
+}
+
+export { SwatchApplyResult }
+
+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
  */
@@ -6884,6 +8439,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 }
@@ -7286,6 +8855,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;
@@ -7294,6 +8865,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;
@@ -8264,6 +9850,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;
@@ -8276,6 +9864,12 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     static FRAME_DURATION: number;
     static MAX_DELTA_SECONDS: number;
     constructor(options: ZylemGameOptions<TGlobals>, wrapperRef: Game<TGlobals>, displayRuntime?: ResolveGameConfigRuntime);
+    /**
+     * Raycast at normalized device coordinates (editor `entity:pick`) and
+     * describe the hit the same way the entity list does, so a consumer can
+     * show name, type, and pose for whatever is under the pointer.
+     */
+    private pickEntityAtNdc;
     /** Publish the placeable entity types the editor's Add palette lists. */
     private publishEntityCatalog;
     /** Spawn a catalog type programmatically (editor `entity:create`). */
@@ -8496,10 +10090,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;
@@ -9140,12 +10736,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;