@rive-app/webgl2-threads 2.49.4 → 2.50.0

package/rive_advanced.mjs.d.ts

@@ -22,6 +22,16 @@ interface RiveOptions {
 declare function Rive(options?: RiveOptions): Promise<RiveCanvas>;
 export default Rive;
 
+/** Resolved script fetch options; see RuntimeLoader.setScriptFetch. */
+export interface ScriptFetchConfig {
+  proxyUrl: string | null;
+  allowedHosts: string[] | null;
+  /** 0 is no limit. */
+  maxRequestsPerMinute: number;
+  /** 0 keeps the runtime's default. */
+  maxResponseBytes: number;
+}
+
 /**
  * RiveCanvas is the main export object that contains references to different Rive classes to help
  * build the Rive render loop for low-level API usage. In addition, this contains multiple methods
@@ -93,6 +103,13 @@ export interface RiveCanvas {
    */
   awaitReplayCaps?(): Promise<void> | undefined;
 
+  /**
+   * @experimental Enables scripts' fetch() for every file, or disables it
+   * with null. Only in builds with script networking (the threaded webgl2
+   * build), so always feature-detect it. Use RuntimeLoader.setScriptFetch.
+   */
+  configureScriptFetch?(options: ScriptFetchConfig | null): void;
+
   /**
    * Loads a Rive file for the runtime and returns a Rive-specific File class
    *

package/runtimeLoader.d.ts

@@ -1,5 +1,43 @@
 import * as rc from "./rive_advanced.mjs";
 export type RuntimeCallback = (rive: rc.RiveCanvas) => void;
+/**
+ * @experimental Options for {@link RuntimeLoader.setScriptFetch}. Requests
+ * sent from this page, or through the reference proxy page, never carry
+ * cookies or other credentials, a referrer or the HTTP cache, and redirects
+ * fail with "policy". A proxy page of your own decides these itself. Either
+ * way, the runtime allows only https: URLs on public hosts, and checks the
+ * URL a response came from against `allowedHosts`.
+ */
+export interface ScriptFetchOptions {
+    /**
+     * URL of a script fetch proxy page, hosted on a cookie-less domain, that
+     * accepts this page's origin. It loads in a hidden iframe added to the
+     * page's `<body>`. Requests then leave from the proxy's origin
+     * under its CSP. On a cross origin isolated page, the proxy page must be
+     * served with `Cross-Origin-Embedder-Policy: require-corp` and
+     * `Cross-Origin-Resource-Policy: cross-origin`. Without it, requests leave
+     * from this page with `fetch()`.
+     */
+    proxyUrl?: string;
+    /**
+     * Hosts scripts may fetch from: exact (`"api.example.com"`), any subdomain
+     * (`"*.example.com"`, which doesn't match `"example.com"`) or any host
+     * (`"*"`). Omitted is `["*"]`; empty allows none. This page's own host is
+     * only allowed when named, e.g. `["*", "www.example.com"]`.
+     */
+    allowedHosts?: string[];
+    /**
+     * Requests scripts may start per minute, counted per scripting VM, so
+     * scripts that share one share the limit. Requests past it wait their turn
+     * rather than fail. 0 is no limit. Default 60.
+     */
+    maxRequestsPerMinute?: number;
+    /**
+     * Largest response body, in bytes, up to 64 MiB. 0 keeps the default of
+     * 16 MiB.
+     */
+    maxResponseBytes?: number;
+}
 export declare class RuntimeLoader {
     private static runtime;
     private static isLoading;
@@ -14,6 +52,8 @@ export declare class RuntimeLoader {
     private static replayWorker;
     private static replayCapsArrived;
     private static readonly replayCapsTimeoutMs;
+    private static scriptFetch;
+    private static warnedNoScriptFetch;
     private static errorCallbackQueue;
     private constructor();
     /**
@@ -76,6 +116,32 @@ export declare class RuntimeLoader {
      */
     static setReplayWorker(enabled: boolean): void;
     static getReplayWorker(): boolean;
+    /**
+     * @experimental Lets scripts in Rive files call `fetch()`. Pass `true` or
+     * options to enable it for every file on the page, `false` to disable it.
+     * Only `@rive-app/webgl2-threads` running its threaded build has it;
+     * elsewhere this warns once and does nothing.
+     *
+     * Enabling it lets any script in any file this page loads send what it
+     * can read to the hosts it may reach. Limit them with `allowedHosts`.
+     * Scripts can't fetch this page's own host unless `allowedHosts` names it.
+     *
+     * Each call replaces the previous options, and any option left out goes
+     * back to its default (an omitted `allowedHosts` allows every host). To
+     * change one option, spread the current ones:
+     *
+     * ```ts
+     * RuntimeLoader.setScriptFetch({
+     *   ...RuntimeLoader.getScriptFetch(),
+     *   maxResponseBytes: 32 * 1024 * 1024,
+     * });
+     * ```
+     *
+     * Disabled by default.
+     */
+    static setScriptFetch(options: ScriptFetchOptions | boolean): void;
+    static getScriptFetch(): ScriptFetchOptions | null;
+    private static applyScriptFetch;
     static setWasmBinary(value: ArrayBuffer | null): void;
     static getWasmBinary(): ArrayBuffer | null;
 }