web: Add OriginAPI to the web player

The new OriginAPI has been added to the web player.
It is used to access behaviour that's specific to the Ruffle origin
(selfhosted, demo or extension).
Unlike the SourceAPI, which manages the whole Ruffle polyfill and
player, it provides minor helper methods and is given to the (internal)
Ruffle player.

The OriginAPI has three implementations: SelfhostedOrigin, DemoOrigin
and ExtensionOrigin. The respective instance is created when installing
the Ruffle instance. When using SourceAPI#createPlayer or #polyfill, the
OriginAPI is given to the then-created (internal) player. This is done
by calling the new RufflePlayerElement#initialize method after creating
it.
The player API now also provides a method to access its OriginAPI.

The previous extension related variables and functions (like
inExtensionPlayer) have been removed from the core code. Instead,
createPanicError now uses OriginAPI calls to display the correct error
message.

Additionally, internalSourceApi and its usages have been replaced by
several functions, reducing the likelihood of future mistakes.

The documentation and code quality have also been generally improved.

Author: Korne127

web/packages/core/src/install.ts

@@ -1,5 +1,6 @@
 import { PublicAPI } from "./public-api";
-import { internalSourceApi } from "./source-api";
+import { getSourceApiImplementation } from "./source-api";
+import { OriginAPI } from "./origin-api";
 
 /**
  * Options to use with this specific installation of Ruffle.
@@ -27,10 +28,12 @@ export interface InstallationOptions {
  * "extension" for browser extensions, and something else for other use cases.
  * Names are unique, and last-installed will replace earlier installations with the same name,
  * regardless of what those installations are or which version they represent.
+ * @param originAPI The OriginAPI of this Ruffle version.
  * @param options Any options used to configure this specific installation of Ruffle.
  */
 export function installRuffle(
     sourceName: string,
+    originAPI: OriginAPI,
     options: InstallationOptions = {},
 ): void {
     let publicAPI: PublicAPI;
@@ -41,8 +44,11 @@ export function installRuffle(
         window.RufflePlayer = publicAPI;
     }
 
-    publicAPI.sources[sourceName] = internalSourceApi;
-    internalSourceApi.options = options;
+    const sourceApiImplementation = getSourceApiImplementation(
+        originAPI,
+        options,
+    );
+    publicAPI.sources[sourceName] = sourceApiImplementation;
 
     // Install the faux plugin detection immediately.
     // This is necessary because scripts such as SWFObject check for the
@@ -51,6 +57,6 @@ export function installRuffle(
     const polyfills =
         "polyfills" in publicAPI.config ? publicAPI.config.polyfills : true;
     if (polyfills !== false) {
-        internalSourceApi.pluginPolyfill();
+        sourceApiImplementation.pluginPolyfill();
     }
 }

web/packages/core/src/internal/errors.tsx

@@ -1,8 +1,7 @@
 export class LoadSwfError extends Error {
-    constructor(public swfUrl: URL | undefined, public inExtensionPlayer: boolean) {
+    constructor(public swfUrl: URL | undefined) {
         super(`Failed to fetch ${swfUrl}`);
         this.swfUrl = swfUrl;
-        this.inExtensionPlayer = inExtensionPlayer;
     }
 }
 

web/packages/core/src/internal/player/inner.tsx

@@ -26,6 +26,7 @@ import { createRuffleBuilder } from "../../load-ruffle";
 import { lookupElement } from "../register-element";
 import { configureBuilder } from "../builder";
 import { DEFAULT_CONFIG } from "../../config";
+import { OriginAPI } from "../../origin-api";
 
 const DIMENSION_REGEX = /^\s*(\d+(\.\d+)?(%)?)/;
 
@@ -184,9 +185,7 @@ export class InnerPlayer {
 
     private volumeSettings: VolumeControls;
 
-    // Whether the last load command originated from the extension player
-    // TODO: Move this variable into the extension code and replace its usages with an API call
-    private inExtensionPlayer = false;
+    private readonly originAPI: OriginAPI;
 
     private readonly debugPlayerInfo: () => string;
     protected readonly onCallbackAvailable: (name: string) => void;
@@ -195,10 +194,12 @@ export class InnerPlayer {
         element: HTMLElement,
         debugPlayerInfo: () => string,
         onCallbackAvailable: (name: string) => void,
+        originAPI: OriginAPI
     ) {
         this.element = element;
         this.debugPlayerInfo = debugPlayerInfo;
         this.onCallbackAvailable = onCallbackAvailable;
+        this.originAPI = originAPI;
 
         this.shadow = this.element.attachShadow({ mode: "open" });
         this.shadow.appendChild(ruffleShadowTemplate.content.cloneNode(true));
@@ -796,9 +797,7 @@ export class InnerPlayer {
     async load(
         options: string | URLLoadOptions | DataLoadOptions,
         isPolyfillElement: boolean = false,
-        inExtensionPlayer: boolean = false
     ): Promise<void> {
-        this.inExtensionPlayer = inExtensionPlayer;
         options = this.checkOptions(options);
 
         if (!this.element.isConnected || this.isUnusedFallbackObject()) {
@@ -892,6 +891,14 @@ export class InnerPlayer {
         return false;
     }
 
+    /**
+     * Returns the OriginAPI of this Ruffle player.
+     * @returns The OriginAPI of this Ruffle player.
+     */
+    getOriginAPI(): OriginAPI {
+        return this.originAPI;
+    }
+
     /**
      * Returns the master volume of the player.
      *
@@ -1891,7 +1898,7 @@ export class InnerPlayer {
         errorArray.push(this.getPanicData());
 
         // Clears out any existing content (ie play button or canvas) and replaces it with the error screen
-        showPanicScreen(this.container, error, errorArray, this.swfUrl);
+        showPanicScreen(this.container, error, errorArray, this.swfUrl, this.originAPI);
 
         // Do this last, just in case it causes any cascading issues.
         this.destroy();
@@ -1934,10 +1941,6 @@ export class InnerPlayer {
         this.displayRootMovieDownloadFailedMessage(false);
     }
 
-    setInExtensionPlayer() {
-        this.inExtensionPlayer = true;
-    }
-
     protected displayRootMovieDownloadFailedMessage(invalidSwf: boolean): void {
         const openInNewTab = this.loadedConfig?.openInNewTab;
         if (
@@ -1950,7 +1953,7 @@ export class InnerPlayer {
         } else {
             const error = invalidSwf
                 ? new InvalidSwfError(this.swfUrl)
-                : new LoadSwfError(this.swfUrl, this.inExtensionPlayer);
+                : new LoadSwfError(this.swfUrl);
             this.panic(error);
         }
     }

web/packages/core/src/internal/player/ruffle-embed-element.ts

@@ -7,6 +7,7 @@ import {
 } from "./inner";
 import { registerElement } from "../register-element";
 import { isSwf } from "../../swf-utils";
+import { OriginAPI } from "../../origin-api";
 
 /**
  * A polyfill html element.
@@ -134,16 +135,22 @@ export class RuffleEmbedElement extends RufflePlayerElement {
      * Creates a RuffleEmbed that will polyfill and replace the given element.
      *
      * @param elem Element to replace.
+     * @param originAPI The OriginAPI that should be used for the Ruffle version
+     * polyfilling the given Flash element.
      * @returns Created RuffleEmbed.
      */
-    static fromNativeEmbedElement(elem: Element): RuffleEmbedElement {
+    static fromNativeEmbedElement(
+        elem: Element,
+        originAPI: OriginAPI,
+    ): RuffleEmbedElement {
         const externalName = registerElement(
             "ruffle-embed",
             RuffleEmbedElement,
         );
         const ruffleObj = document.createElement(
             externalName,
         ) as RuffleEmbedElement;
+        ruffleObj.initialize(originAPI);
         copyElement(elem, ruffleObj);
 
         return ruffleObj;

web/packages/core/src/internal/player/ruffle-object-element.ts

@@ -9,6 +9,7 @@ import { FLASH_ACTIVEX_CLASSID } from "../../flash-identifiers";
 import { registerElement } from "../register-element";
 import { RuffleEmbedElement } from "./ruffle-embed-element";
 import { isSwf } from "../../swf-utils";
+import { OriginAPI } from "../../origin-api";
 
 /**
  * Find and return the first value in obj with the given key.
@@ -250,16 +251,22 @@ export class RuffleObjectElement extends RufflePlayerElement {
      * Creates a RuffleObject that will polyfill and replace the given element.
      *
      * @param elem Element to replace.
+     * @param originAPI The OriginAPI that should be used for the Ruffle version
+     * polyfilling the given Flash element.
      * @returns Created RuffleObject.
      */
-    static fromNativeObjectElement(elem: Element): RuffleObjectElement {
+    static fromNativeObjectElement(
+        elem: Element,
+        originAPI: OriginAPI,
+    ): RuffleObjectElement {
         const externalName = registerElement(
             "ruffle-object",
             RuffleObjectElement,
         );
         const ruffleObj: RuffleObjectElement = document.createElement(
             externalName,
         ) as RuffleObjectElement;
+        ruffleObj.initialize(originAPI);
 
         // Avoid copying embeds-inside-objects to avoid double polyfilling.
         for (const embedElem of Array.from(