Split movie host contract

docs/PROJECT-STRUCTURE.md

@@ -165,7 +165,9 @@ implementations. `engine/Age.Engine/Hosting/IDiagnosticHost.cs` owns recoverable
 reporting contracts, while `engine/Age.Engine/Hosting/ILifecycleHost.cs` owns script-context entry/exit, sleep and
 timed-deadline waiting, frame yield, and scene reset. `engine/Age.Engine/Hosting/IAudioHost.cs` owns BGM, voice,
 SFX, fade, volume, and route-control contracts, including the compatibility overload/default chains used by
-simple hosts. `IHost` inherits all three focused contracts; their required and default behavior is unchanged.
+simple hosts. `engine/Age.Engine/Hosting/IMovieHost.cs` owns ordinary, positioned, mask-transition, activity-query,
+and modal movie playback contracts. `IHost` inherits all four focused contracts; their required and default
+behavior is unchanged, and movie/graphics transport records remain in their existing locations for now.
 
 `engine/Age.Engine/Model/GfxState.cs` retains cross-domain retained-graphics coordination.
 `engine/Age.Engine/Model/GfxState.Contracts.cs` owns its public render, transition, diagnostic, persistence,

docs/remake-architecture-and-roadmap.md

@@ -770,6 +770,12 @@ do not mix mechanical moves with semantic changes.
    compatibility overloads/default chains, and existing host classes remain behaviorally unchanged. Runtime
    validation remains green.
 
+   The third bounded contract slice introduced `IMovieHost` for ordinary, positioned, mask-transition, activity
+   queries for movie surfaces, and modal playback. `IHost` inherits the focused contract; all five default
+   members and existing host classes remain behaviorally unchanged. `GfxState` and
+   `MovieMaskTransitionRequest` remain in their prior locations pending a separate dependency-cleanup slice.
+   Runtime validation remains green.
+
 4. **Make the build graph express source ownership.** Stop linking production `.cs` files from `godot/` and
    `tools/movie-corpus-gate/` into `Age.Engine.Tests`. Extract the platform-neutral frontend/movie/diagnostic
    code into a small production project referenced by Godot, tests, and the corpus gate. Retain both existing
@@ -1129,9 +1135,9 @@ layer's rendering diverges from ADV; save layout.
 
 ## 8. Immediate next step
 Continue step 3 of the **codebase consolidation** maintenance slice: clarify runtime contracts without changing
-behavior or the aggregate host accepted by the VM. With diagnostic, lifecycle, and audio contracts established
+behavior or the aggregate host accepted by the VM. With diagnostic, lifecycle, audio, and movie contracts
-beneath `IHost`, introduce the movie host contract next while leaving movie request/graphics transport records in
+established beneath `IHost`, move the neutral `MovieMaskTransitionRequest` contract from `Hosting` to `Model` next
-their current locations for a separate dependency-cleanup slice; preserve every required/default member and all
+to remove `GfxState`'s reverse dependency on the host namespace, preserving the record's public shape and every
-existing host implementations.
+consumer before separating larger host domains.
 Concrete playthrough blockers may still preempt this bounded maintenance work; the consolidation effort does
 not replace Phase B gameplay validation or the open cross-platform gates.

engine/Age.Engine/Hosting/IHost.cs

@@ -48,7 +48,7 @@ public enum SurfaceBlackFadeDirection
     ToBlack,
 }
 
-public interface IHost : IDiagnosticHost, ILifecycleHost, IAudioHost
+public interface IHost : IDiagnosticHost, ILifecycleHost, IAudioHost, IMovieHost
 {
     /// <summary>Present AGERc's modal full-width editor. Cancel preserves CurrentText.</summary>
     FullwidthTextEditResult EditFullwidthString(FullwidthTextEditRequest request)
@@ -171,28 +171,4 @@ public interface IHost : IDiagnosticHost, ILifecycleHost, IAudioHost
     }
     void DrawTexture(int slot, int srcX, int srcY, int width, int height, int dstX, int dstY);
     (int Width, int Height) GetTextureSize(int slot);
-    // Native op 0x236 binds a movie decoder to an existing retained texture surface.
-    // Playback is non-modal: the VM advances to the following instruction while the host publishes frames.
-    /// <returns>The initialized movie graph's stop position in truncated integer milliseconds, or null
-    /// when the host could not obtain usable timing metadata. Native op 0x23f queries this state
-    /// immediately after 0x236 returns.</returns>
-    long? PlayMovieToSurface(long resourceId, int surfaceSlot, long movieFlags, long syncMask) => null;
-    // Native op 0x241 uses the same graph/surface lifecycle as 0x236, but seeks the graph before
-    // playback configuration. Hosts without positioned decoding may fall back to ordinary playback.
-    long? PlayMovieToSurfaceAtPosition(
-        long resourceId, int surfaceSlot, long movieFlags, long syncMask, long positionMs)
-        => PlayMovieToSurface(resourceId, surfaceSlot, movieFlags, syncMask);
-    // Native op 0x24d captures a retained range into the scratch surface, then publishes each
-    // decoded movie frame's green channel as an exact packed-alpha mask. A nonvisual host completes
-    // the lifecycle immediately so a following 0x21c can never strand script execution.
-    void PlayMovieMaskTransition(GfxState gfx, MovieMaskTransitionRequest request)
-    {
-        gfx.QueueMovieMaskTransition(request);
-        gfx.CompleteMovieMaskTransition(request.SurfaceSlot);
-    }
-    bool IsMovieSurfaceActive(int surfaceSlot) => false;
-    // Native op 0x20f uses a universal packed id and parks script execution until the movie
-    // reaches EOF or the player cancels it. The decoder remains asynchronous; the interactive host
-    // owns the modal wait so its render loop can continue publishing frames.
-    void PlayModalMovieToSurface(long resourceId, int surfaceSlot, long movieFlags) { }
 }

engine/Age.Engine/Hosting/IMovieHost.cs

@@ -0,0 +1,35 @@
+using Age.Engine.Model;
+
+namespace Age.Engine.Hosting;
+
+public interface IMovieHost
+{
+    // Native op 0x236 binds a movie decoder to an existing retained texture surface.
+    // Playback is non-modal: the VM advances to the following instruction while the host publishes frames.
+    /// <returns>The initialized movie graph's stop position in truncated integer milliseconds, or null
+    /// when the host could not obtain usable timing metadata. Native op 0x23f queries this state
+    /// immediately after 0x236 returns.</returns>
+    long? PlayMovieToSurface(long resourceId, int surfaceSlot, long movieFlags, long syncMask) => null;
+
+    // Native op 0x241 uses the same graph/surface lifecycle as 0x236, but seeks the graph before
+    // playback configuration. Hosts without positioned decoding may fall back to ordinary playback.
+    long? PlayMovieToSurfaceAtPosition(
+        long resourceId, int surfaceSlot, long movieFlags, long syncMask, long positionMs)
+        => PlayMovieToSurface(resourceId, surfaceSlot, movieFlags, syncMask);
+
+    // Native op 0x24d captures a retained range into the scratch surface, then publishes each
+    // decoded movie frame's green channel as an exact packed-alpha mask. A nonvisual host completes
+    // the lifecycle immediately so a following 0x21c can never strand script execution.
+    void PlayMovieMaskTransition(GfxState gfx, MovieMaskTransitionRequest request)
+    {
+        gfx.QueueMovieMaskTransition(request);
+        gfx.CompleteMovieMaskTransition(request.SurfaceSlot);
+    }
+
+    bool IsMovieSurfaceActive(int surfaceSlot) => false;
+
+    // Native op 0x20f uses a universal packed id and parks script execution until the movie
+    // reaches EOF or the player cancels it. The decoder remains asynchronous; the interactive host
+    // owns the modal wait so its render loop can continue publishing frames.
+    void PlayModalMovieToSurface(long resourceId, int surfaceSlot, long movieFlags) { }
+}