@m2c2kit/core 0.3.17 → 0.3.18

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Canvas, Typeface, TypefaceFontProvider, Image, CanvasKit, Surface, Font, Paint, ParagraphBuilder, Paragraph, FontMgr, Path, PaintStyle } from 'canvaskit-wasm';
+import { Canvas, Typeface, TypefaceFontProvider, Image, Paint, CanvasKit, Surface, Font, ParagraphBuilder, Paragraph, FontMgr, Path, PaintStyle } from 'canvaskit-wasm';
 
 declare class GlobalVariables {
     now: number;
@@ -175,6 +175,13 @@ interface Layout {
  */
 type RgbaColor = [number, number, number, number];
 
+/**
+ * Map of placeholders to values for use in string interpolation.
+ */
+interface StringInterpolationMap {
+    [placeholder: string]: string;
+}
+
 interface TextOptions {
     /** Text to be displayed */
     text?: string;
@@ -184,6 +191,10 @@ interface TextOptions {
     fontColor?: RgbaColor;
     /** Size of text. Default is Constants.DEFAULT_FONT_SIZE (16) */
     fontSize?: number;
+    /** Map of placeholders to values for use in string interpolation during localization. */
+    interpolation?: StringInterpolationMap;
+    /** If true, try to use a localized version of the text. Default is true. */
+    localize?: boolean;
 }
 
 /**
@@ -224,7 +235,9 @@ declare enum M2NodeType {
     Label = "Label",
     TextLine = "TextLine",
     Shape = "Shape",
-    Composite = "Composite"
+    Composite = "Composite",
+    SoundPlayer = "SoundPlayer",
+    SoundRecorder = "SoundRecorder"
 }
 
 type EasingFunction = (
@@ -551,15 +564,15 @@ interface IDataStore {
     /** Sets the value of an item. The key will be saved to the store as provided;
      * if namespacing or other formatting is desired, it must be done before
      * calling this method. activityId can be used by the store for indexing. */
-    setItem(key: string, value: string | number | boolean | object | undefined | null, activityId: string): Promise<string>;
+    setItem(key: string, value: string | number | boolean | object | undefined | null, activityPublishUuid: string): Promise<string>;
     /** Gets the value of an item by its key. */
     getItem<T extends string | number | boolean | object | undefined | null>(key: string): Promise<T>;
     /** Deletes an item by its key. */
     deleteItem(key: string): Promise<void>;
     /** Deletes all items. */
-    clearItemsByActivityId(activityId: string): Promise<void>;
+    clearItemsByActivityPublishUuid(activityPublishUuid: string): Promise<void>;
     /** Returns keys of all items. */
-    itemsKeysByActivityId(activityId: string): Promise<string[]>;
+    itemsKeysByActivityPublishUuid(activityPublishUuid: string): Promise<string[]>;
     /** Determines if the key exists. */
     itemExists(key: string): Promise<boolean>;
 }
@@ -621,14 +634,20 @@ interface Activity {
      * @param options - options for the callback.
      */
     onData(callback: (activityResultsEvent: ActivityResultsEvent) => void, options?: CallbackOptions): void;
-    /** The activity's parent session unique identifier. */
+    /** The activity's parent session unique identifier. This is newly generated each session. */
     sessionUuid: string;
-    /** The activity's unique identifier. NOTE: This is newly generated each session. The uuid for an activity will vary across sessions. */
+    /** The activity's unique identifier. This is newly generated each session. The UUID for an activity will vary across sessions. */
     uuid: string;
     /** Human-friendly name of this activity */
     name: string;
     /** Short identifier of this activity */
     id: string;
+    /** Persistent unique identifier (UUID) of the activity. Required for games. Optional or empty string if a survey. */
+    publishUuid: string;
+    /** The ID of the study (protocol, experiment, or other aggregate) that contains the repeated administrations of this activity. The ID should be short, url-friendly, human-readable text (no spaces, special characters, or slashes), e.g., `nyc-aging-cohort`. */
+    studyId?: string;
+    /** Unique identifier (UUID) of the study (protocol, experiment, or other aggregate) that contains the administration of this activity. */
+    studyUuid?: string;
     /** The value of performance.now() immediately before the activity begins */
     beginTimestamp: number;
     /** The value of new Date().toISOString() immediately before the activity begins */
@@ -659,9 +678,13 @@ interface BrowserImage {
     /** URL of image asset (svg, png, jpg) to render and load */
     url?: string;
     /** If true, the image will not be fully loaded until it is needed. Default
-     * is false. Lazy loading is useful for localized images or large "banks"
-     * of images. These should be lazy loaded because they may not be needed. */
+     * is false. Lazy loading is useful for large "banks" of images. These should
+     * be lazy loaded because they may not be needed. */
     lazy?: boolean;
+    /** If true, try to use a localized version of the image. Localized images
+     * are loaded on demand and are not preloaded. Only an image whose asset
+     * is provided as a URL can be localized. Default is false. */
+    localize?: boolean;
 }
 
 /**
@@ -689,27 +712,6 @@ interface DefaultParameter extends JsonSchema {
     default: any;
 }
 
-/**
- * Translations is a map of a locale to a map of keys to translations.
- *
- * @example
- * ```
- * const translations: Translations = {
- *   "en-US": {
- *     "NEXT_BUTTON": "Next"
- *   },
- *   "es-MX": {
- *     "NEXT_BUTTON": "Siguiente"
- *   }
- * }
- * ```
- */
-interface Translations {
-    [locale: string]: {
-        [key: string]: string;
-    };
-}
-
 /**
  * Font url and raw data that has been shared with other games in the session.
  *
@@ -754,14 +756,207 @@ interface ModuleMetadata {
     };
 }
 
+interface SoundAsset {
+    /** Name of the sound to use when referring to it within m2c2kit, such as
+     * when creating a `SoundPlayer` node. */
+    soundName: string;
+    /** URL of sound to load */
+    url: string;
+    /** If true, the sound will not be fully loaded until it is needed. Default
+     * is false. Lazy loading is useful for sounds involved in localization.
+     * These should be lazy loaded because they may not be needed.
+     */
+    lazy?: boolean;
+}
+
+/**
+ * A map of a locale to a map of keys to translated text and font information.
+ *
+ * @remarks When it comes to fonts, the `Translation` object only specifies
+ * which fonts to use for text. The actual fonts must be provided as part of
+ * the `GameOptions` object with names that match the names specified in the
+ * `Translation` object.
+ *
+ * The below example defines a translation object for use in three locales:
+ * en-US, es-MX, and hi-IN.
+ *
+ * In the `configuration` object, the `baseLocale` property is en-US. This
+ * means that the en-US locale is the locale from which the "native"
+ * resources originate.
+ *
+ * The property `localeName` is human-readable text of the locale that can
+ * be displayed to the user. For example, `en-US` might have the locale name
+ * `English`. The property `localeSvg` is an image of the locale, as an SVG
+ * string and its height and width. This is so the locale can be displayed to
+ * the user if the locale uses a script that is not supported in the default
+ * font, and a locale-specific font is not yet loaded.
+ *
+ * For en-US and es-MX, the game's default font will be used for all text
+ * because the `fontName` property is not specified for these locales. For
+ * hi-IN, the `devanagari` font will be used for all text.
+ *
+ * `EMOJI_WELCOME` uses an emoji, and it will not display properly unless an
+ * `emoji` font is added. The `additionalFontName` property is used to
+ * specify an additional font or fonts to use as well as the locale's font.
+ * For en-US and es-MX, the `emoji` font plus the game's default font will be
+ * used for the `EMOJI_WELCOME` text. For hi-IN, the `emoji` font plus the
+ * `devanagari` font will be used for the `EMOJI_WELCOME` text.
+ *
+ * `OK_BUTTON` uses the game's default font for all locales. Because hi-IN
+ * specified a font name, the `overrideFontName` property with a value of
+ * `default` is used to specify that the game's default font should be used
+ * instead of the locale's font, devanagari.
+ *
+ * `BYE` uses interpolation. `{{name}}` is a placeholder that will be replaced,
+ * at runtime, with the value of the `name` key in the `options` object passed
+ * to the `t` or `tf` methods of the `I18n` object. If the placeholder is not
+ * found in `options`, an error will be thrown.
+ *
+ * @example
+ *
+ * ```
+ * const translation: Translation = {
+ *   "configuration": {
+ *    "baseLocale": "en-US"
+ *   },
+ *   "en-US": {
+ *     localeName: "English",
+ *     "NEXT_BUTTON": "Next"
+ *     "EMOJI_WELCOME": {
+ *       text: "👋 Hello",
+ *       additionalFontName: ["emoji"]
+ *     },
+ *     "OK_BUTTON": "OK",
+ *     "BYE": "Goodbye, {{name}}."
+ *   },
+ *   "es-MX": {
+ *     localeName: "Español",
+ *     "NEXT_BUTTON": "Siguiente"
+ *     "EMOJI_WELCOME": {
+ *       text: "👋 Hola",
+ *       additionalFontName: ["emoji"]
+ *     },
+ *     "OK_BUTTON": "OK",
+ *     "BYE": "Adiós, {{name}}."
+ *   },
+ *   "hi-IN": {
+ *     localeName: "Hindi",
+ *     localeSvg: {
+ *       // from https://commons.wikimedia.org/wiki/File:Hindi.svg, not copyrighted
+ *       // note: To save space, the next line is not the full, working SVG string from the above URL.
+ *       svgString: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 304 168" xml:space="preserve"><path d="m45.223..."/></svg>`,
+ *       height: 44,
+ *       width: 80,
+ *     },
+ *     fontName: "devanagari",
+ *     "NEXT_BUTTON": "अगला"
+ *     "EMOJI_WELCOME": {
+ *       text: "👋 नमस्कार",
+ *       additionalFontName: ["emoji"]
+ *     },
+ *     "OK_BUTTON": {
+ *       text: "OK",
+ *       overrideFontName: "default"
+ *     },
+ *    "BYE": "अलविदा {{name}}."
+ *   }
+ * }
+ *
+ * ...
+ *
+ * const nextButton = new Button({
+ *  text: "NEXT_BUTTON"
+ *  ...
+ * })
+ *
+ * const byeLabel = new Label({
+ *  text: "BYE",
+ *  interpolation: {
+ *    name: "Alice"
+ *  }
+ *  ...
+ * }
+ * ```
+ */
+type Translation = LocaleTranslationMap & {
+    configuration?: TranslationConfiguration;
+};
+interface TranslationConfiguration {
+    /** The locale from which translations and adaptations are made to adjust to different regions and languages. This is the locale from which the base or unlocalized resources originate. */
+    baseLocale: string;
+}
+interface LocaleSvg {
+    /** The HTML SVG tag, in string form, that will be rendered and loaded.
+     * Must begin with &#60;svg> and end with &#60;/svg> */
+    svgString: string;
+    /** Height to scale image to */
+    height: number;
+    /** Width to scale image to */
+    width: number;
+}
+type LocaleTranslationMap = {
+    [locale: string]: {
+        /** The font name or names to use for all text in the locale. If omitted,
+         * the game's default font will be used. */
+        fontName?: string | string[];
+        /** Human-readable text of the locale that can be displayed to the user. For example, `en-US` might have the locale name `English` */
+        localeName?: string;
+        /** Image of the locale, as an SVG string, that can be displayed to the user. Some locales, in their native script, might not be supported in the default font. For example, Hindi script cannot be displayed in Roboto font. It would be inefficient to load all the possible extra fonts simply to display the locale to the user. Thus, in lieu of a string, the locale can be displayed to the user as an SVG. Only if that locale is selected, the font supporting that locale will be loaded. */
+        localeSvg?: LocaleSvg;
+    } & {
+        /** The translated text or the translated text with custom font information. Note: `LocaleSvg` is included in the union only to satisfy TypeScript compiler. */
+        [key: string]: string | TextWithFontCustomization | LocaleSvg;
+    };
+};
+/**
+ * A translated string with custom font information to be applied only to this
+ * string.
+ */
+interface TextWithFontCustomization {
+    /** The translated string. */
+    text: string;
+    /** Font name(s) to _add to_ the locale's font name(s) when displaying text. */
+    additionalFontName?: string | Array<string>;
+    /** Font name(s) to use _in place of_ the locale's font name(s) when
+     * displaying text. Use `default` to indicate that the game's default font
+     * should be used instead of the locale's font names(s) */
+    overrideFontName?: string | Array<string>;
+}
+interface TextAndFont {
+    /** The translated string. */
+    text?: string;
+    /** Font name to use when displaying the text. */
+    fontName?: string;
+    /** Font names to use when displaying the text. */
+    fontNames?: Array<string>;
+}
+
+/**
+ * Localization information that is passed to the I18n constructor.
+ */
+interface LocalizationOptions {
+    /** Locale to use for localization when running the game, or "auto" to request from the environment. */
+    locale?: string;
+    /** Locale to use if requested locale translation is not available, or if "auto" locale was requested and environment cannot provide a locale. Default is `en-US`.*/
+    fallbackLocale?: string;
+    /** Font color for strings or outline color for images when a requested locale's translation or image is missing. This is useful in development to call attention to missing localization assets. */
+    missingLocalizationColor?: RgbaColor;
+    /** Translation for localization. */
+    translation?: Translation;
+    /** Additional translation for localization. This will typically be provided through `setParameters()` at runtime. This translation be merged into the existing translation and will overwrite any existing translation with the same key-value pairs. Thus, this can be used to modify an existing translation, either in whole or in part. */
+    additionalTranslation?: Translation;
+}
+
 /**
  * Options to specify HTML canvas, set game canvas size, and load game assets.
  */
-interface GameOptions {
+interface GameOptions extends LocalizationOptions {
     /** Human-friendly name of this game */
     name: string;
-    /** Short identifier of this game; unique among published games and url-friendly (no spaces, special characters, or slashes)*/
+    /** Short identifier of this game; unique among published games and url-friendly (no spaces, special characters, or slashes). */
     id: string;
+    /** Persistent unique identifier (UUID) of this game; unique among published games. The m2c2kit CLI will generate this property automatically, and you should not change it. If not using the CLI, use a website like https://www.uuidgenerator.net/version4 to generate this value. */
+    publishUuid: string;
     /** Version of this game */
     version: string;
     /** Uri (repository, webpage, or other location where full information about the game can be found) */
@@ -786,6 +981,8 @@ interface GameOptions {
     fonts?: Array<FontAsset>;
     /** Array of BrowserImage objects to render and load */
     images?: Array<BrowserImage>;
+    /** Array of SoundAsset objects to fetch and decode */
+    sounds?: Array<SoundAsset>;
     /** Show FPS in upper left corner? Default is false */
     showFps?: boolean;
     /** Color of the html body, if the game does not fill the screen. Useful for showing scene boundaries. Default is the scene background color */
@@ -796,8 +993,6 @@ interface GameOptions {
     fpsMetricReportThreshold?: number;
     /** Advance through time step-by-step, for development and debugging */
     timeStepping?: boolean;
-    /** Translations for localization. */
-    translations?: Translations;
     /** Show logs for WebGl activity? */
     logWebGl?: boolean;
     /** Should games within a session share wasm and font assets that have identical filenames, in order to reduce bandwidth? Default is true. */
@@ -810,35 +1005,103 @@ interface GameData extends ActivityKeyValueData {
     trials: Array<TrialData>;
 }
 
-/**
- * Localization information that is passed to the I18n constructor.
- */
-interface LocalizationOptions {
-    /** Locale to use for localization, or "auto" to request from the environment. */
-    locale: string;
-    /** Locale to use if requested locale translation is not available, or if "auto" locale was requested and environment cannot provide a locale. */
-    fallbackLocale?: string;
-    /** Font color for strings that are missing translation and use the fallback locale or untranslated string. */
-    missingTranslationFontColor?: RgbaColor;
-    /** Translations for localization. */
-    translations?: Translations;
-    /** Additional translations for localization provided through game parameters. These will be merged into existing translations. */
-    additionalTranslations?: Translations;
+interface TranslationOptions {
+    [key: string]: unknown;
+}
+interface TextLocalizationResult {
+    text: string;
+    fontName?: string;
+    fontNames?: string[];
+    isFallbackOrMissingTranslation: boolean;
 }
-
 declare class I18n {
-    private _translations;
+    private _translation;
     locale: string;
     fallbackLocale: string;
-    private environmentLocale;
-    options: LocalizationOptions;
-    static makeLocalizationParameters(): GameParameters;
-    constructor(options: LocalizationOptions);
-    t(key: string, useFallback?: boolean): string | undefined;
-    get translations(): Translations;
-    set translations(value: Translations);
+    baseLocale: string;
+    missingLocalizationColor: RgbaColor | undefined;
+    game: Game;
+    /**
+     * The I18n class localizes text and images.
+     *
+     * @param game - game instance
+     * @param options - {@link LocalizationOptions}
+     */
+    constructor(game: Game, options: LocalizationOptions);
+    /**
+     * Initializes the I18n instance and sets the initial locale.
+     *
+     * @remarks If the game instance has been configured to use a data store,
+     * the previously used locale and fallback locale will be retrieved from the
+     * data store if they have been previously set.
+     */
+    initialize(): Promise<void>;
+    private configureInitialLocale;
+    private localeTranslationAvailable;
+    switchToLocale(locale: string): void;
+    /**
+     *
+     * @param key - Translation key
+     * @param interpolation - Interpolation keys and values to replace
+     * placeholders in the translated text
+     * @returns a `TextLocalizationResult` object with the localized text, font
+     * information, and whether the translation is a fallback.
+     */
+    getTextLocalization(key: string, interpolation?: StringInterpolationMap): TextLocalizationResult;
+    /**
+     * Returns the translation text for the given key in the current locale.
+     *
+     * @remarks Optional interpolation keys and values can be provided to replace
+     * placeholders in the translated text. Placeholders are denoted by double
+     * curly braces.
+     *
+     * @param key - key to look up in the translation
+     * @param options - `TranslationOptions`, such as interpolation keys/values
+     * and whether to translate using the fallback locale
+     * @returns the translation text for the key in the current locale, or
+     * undefined if the key is not found
+     *
+     * @example
+     *
+     * ```
+     * const translation: Translation = {
+     *   "en-US": {
+     *     "GREETING": "Hello, {{name}}."
+     *   }
+     * }
+     * ...
+     * i18n.t("GREETING", { name: "World" }); // returns "Hello, World."
+     *
+     * ```
+     */
+    t(key: string, options?: TranslationOptions): string | undefined;
+    /**
+     * Returns the translation text and font information for the given key in the
+     * current locale.
+     *
+     * @remarks Optional interpolation keys and values can be provided to replace
+     * placeholders in the translated text. Placeholders are denoted by double
+     * curly braces. See method {@link I18n.t()} for interpolation example.
+     *
+     * @param key - key to look up in the translation
+     * @param options - `TranslationOptions`, such as interpolation keys/values
+     * and whether to translate using the fallback locale
+     * @returns the translation text and font information for the key in the
+     * current locale, or undefined if the key is not found
+     */
+    tf(key: string, options?: TranslationOptions): TextAndFont | undefined;
+    private getKeyText;
+    private getKeyTextAndFont;
+    private insertInterpolations;
+    get translation(): Translation;
+    set translation(value: Translation);
     private getEnvironmentLocale;
-    private mergeAdditionalTranslations;
+    private mergeAdditionalTranslation;
+    static makeLocalizationParameters(): GameParameters;
+    private isTextWithFontCustomization;
+    private isStringOrTextWithFontCustomization;
+    private isStringArray;
+    private isString;
 }
 
 /**
@@ -995,13 +1258,26 @@ declare class FontManager {
  * additional properties.
  */
 interface M2Image {
+    /** Name of the image, as it will be referred to when creating a sprite. */
     imageName: string;
+    /** The image in CanvasKit format. */
     canvaskitImage: Image | undefined;
     width: number;
     height: number;
+    /** Status of the image: Deferred, Loading, Ready, or Error. */
     status: M2ImageStatus;
+    /** For an image that will be fetched, this is the URL that will be attempted. This may have localization applied. */
     url?: string;
+    /** Is this image a fallback localized image? */
+    isFallback: boolean;
+    /** For an image that will be fetched, the original URL before any localization. */
+    originalUrl?: string;
+    /** For a localized image that will be fetched, additional URLs to try if the URL in `url` fails. */
+    fallbackLocalizationUrls?: Array<string>;
+    /** An image defined by an SVG string. */
     svgString?: string;
+    /** Try to localize the image by fetching a locale-specific image? Default is false. */
+    localize: boolean;
 }
 declare const M2ImageStatus: {
     /** Image was set for lazy loading, and loading has not yet been requested. */
@@ -1026,6 +1302,7 @@ declare class ImageManager {
     private scale?;
     private game;
     private baseUrls;
+    missingLocalizationImagePaint?: Paint;
     constructor(game: Game, baseUrls: GameBaseUrls);
     /**
      * Loads image assets and makes them ready to use during the game initialization.
@@ -1051,6 +1328,25 @@ declare class ImageManager {
      * @returns A promise that completes when all images have loaded
      */
     loadImages(browserImages: Array<BrowserImage>): Promise<void>;
+    private configureImageLocalization;
+    /**
+     * Localizes the image URL by appending the locale to the image URL,
+     * immediately before the file extension.
+     *
+     * @remarks For example, `https://url.com/file.png` in en-US locale
+     * becomes `https://url.com/file.en-US.png`. A URL without an extension
+     * will throw an error.
+     *
+     * @param url - url of the image
+     * @param locale - locale in format of xx-YY, where xx is the language code
+     * and YY is the country code
+     * @returns localized url
+     */
+    private localizeImageUrl;
+    /**
+     * Sets an image to be re-rendered within the current locale.
+     */
+    reinitializeLocalizedImages(): void;
     private checkImageNamesForDuplicates;
     /**
      * Makes ready to the game a m2c2kit image ({@link M2Image}) that was
@@ -1113,6 +1409,142 @@ declare class ImageManager {
     private removeScratchCanvas;
 }
 
+interface M2Sound {
+    soundName: string;
+    data: ArrayBuffer | undefined;
+    audioBuffer: AudioBuffer | undefined;
+    url: string;
+    status: M2SoundStatus;
+}
+declare const M2SoundStatus: {
+    /** Sound was set for lazy loading, and loading has not yet been requested. */
+    readonly Deferred: "Deferred";
+    /** Sound is indicated for fetching, but fetching has not begun. */
+    readonly WillFetch: "WillFetch";
+    /** Sound is being fetched. */
+    readonly Fetching: "Fetching";
+    /** Sound has been fetched. */
+    readonly Fetched: "Fetched";
+    /** Sound is being decoded. */
+    readonly Decoding: "Decoding";
+    /** Sound has fully finished loading and is ready to use. */
+    readonly Ready: "Ready";
+    /** Error occurred in loading. */
+    readonly Error: "Error";
+};
+type M2SoundStatus = (typeof M2SoundStatus)[keyof typeof M2SoundStatus];
+
+/**
+ * Fetches, loads, and provides sounds to the game.
+ *
+ * @internal For m2c2kit library use only
+ */
+declare class SoundManager {
+    private sounds;
+    private game;
+    private baseUrls;
+    private _audioContext?;
+    constructor(game: Game, baseUrls: GameBaseUrls);
+    get audioContext(): AudioContext;
+    /**
+     * Loads sound assets during the game initialization.
+     *
+     * @internal For m2c2kit library use only
+     *
+     * @remarks Typically, a user won't call this because the m2c2kit
+     * framework will call this automatically. At initialization, sounds can
+     * only be fetched, not decoded because the AudioContext can not yet
+     * be created (it requires a user interaction).
+     *
+     * @param soundAssets - array of SoundAsset objects
+     */
+    initializeSounds(soundAssets: Array<SoundAsset> | undefined): Promise<void>;
+    /**
+     * Loads an array of sound assets and makes them ready for the game.
+     *
+     * @remarks Loading a sound consists of 1) fetching the sound file and 2)
+     * decoding the sound data. The sound is then ready to be played. Step 1
+     * can be done at any time, but step 2 requires an `AudioContext`, which
+     * can only be created after a user interaction. If a play `Action` is
+     * attempted before the sound is ready (either it has not been fetched or
+     * decoded), the play `Action` will log a warning to the console and the
+     * loading process will continue in the background, and the sound will play
+     * when ready. This `loadSounds()` method **does not** have to be awaited.
+     *
+     * @param soundAssets - an array of {@link SoundAsset}
+     * @returns A promise that completes when all sounds have loaded
+     */
+    loadSounds(soundAssets: Array<SoundAsset>): Promise<void>;
+    private fetchSounds;
+    /**
+     * Fetches a m2c2kit sound ({@link M2Sound}) that was previously
+     * initialized with lazy loading.
+     *
+     * @internal For m2c2kit library use only
+     *
+     * @param m2Sound - M2Sound to fetch
+     * @returns A promise that completes when sounds have been fetched
+     */
+    fetchDeferredSound(m2Sound: M2Sound): Promise<void>;
+    /**
+     * Checks if the SoundManager has sounds needing decoding.
+     *
+     * @internal For m2c2kit library use only
+     *
+     * @returns true if there are sounds that have been fetched and are waiting
+     * to be decoded (status is `M2SoundStatus.Fetched`)
+     */
+    hasSoundsToDecode(): boolean;
+    /**
+     * Decodes all fetched sounds from bytes to an `AudioBuffer`.
+     *
+     * @internal For m2c2kit library use only
+     *
+     * @remarks This method will be called after the `AudioContext` has been
+     * created and if there are fetched sounds waiting to be decoded.
+     *
+     * @returns A promise that completes when all fetched sounds have been decoded
+     */
+    decodeFetchedSounds(): Promise<void[]>;
+    /**
+     * Decodes a sound from bytes to an `AudioBuffer`.
+     *
+     * @param sound - sound to decode
+     */
+    private decodeSound;
+    /**
+     * Returns a m2c2kit sound ({@link M2Sound}) that has been entered into the
+     * SoundManager.
+     *
+     * @internal For m2c2kit library use only
+     *
+     * @remarks Typically, a user won't need to call this because sound
+     * initialization and processing is handled by the framework.
+     *
+     * @param soundName - sound's name as defined in the game's sound assets
+     * @returns a m2c2kit sound
+     */
+    getSound(soundName: string): M2Sound;
+    /**
+     * Frees up resources allocated by the SoundManager.
+     *
+     * @internal For m2c2kit library use only
+     *
+     * @remarks This will be done automatically by the m2c2kit library; the
+     * end-user must not call this.
+     */
+    dispose(): void;
+    /**
+     * Gets names of sounds entered in the `SoundManager`.
+     *
+     * @remarks These are sounds that the `SoundManager` is aware of. The sounds
+     * may not be ready to play (may not have been fetched or decoded yet).
+     *
+     * @returns array of sound names
+     */
+    getSoundNames(): Array<string>;
+}
+
 /** Key value pairs of file URLs and hashed file URLs */
 type Manifest = {
     [originalUrl: string]: string;
@@ -1133,6 +1565,9 @@ declare class Game implements Activity {
     uuid: string;
     name: string;
     id: string;
+    publishUuid: string;
+    studyId?: string;
+    studyUuid?: string;
     moduleMetadata: ModuleMetadata;
     readonly canvasKitWasmVersion = "__CANVASKITWASM_VERSION__";
     options: GameOptions;
@@ -1155,6 +1590,7 @@ declare class Game implements Activity {
     };
     private _fontManager?;
     private _imageManager?;
+    private _soundManager?;
     manifest?: Manifest;
     /**
      * The base class for all games. New games should extend this class.
@@ -1205,6 +1641,22 @@ declare class Game implements Activity {
     set fontManager(fontManager: FontManager);
     get imageManager(): ImageManager;
     set imageManager(imageManager: ImageManager);
+    get soundManager(): SoundManager;
+    set soundManager(soundManager: SoundManager);
+    /**
+     * Adds prefixes to a key to ensure that keys are unique across activities
+     * and studies.
+     *
+     * @remarks When a value is saved to the key-value data store, the key must
+     * be prefixed with additional information to ensure that keys are unique.
+     * The prefixes will include the activity id and publish UUID, and possibly
+     * the study id and study UUID, if they are set (this is so that keys are
+     * unique across different studies that might use the same activity).
+     *
+     * @param key - item key to add prefixes to
+     * @returns the item key with prefixes added
+     */
+    private addPrefixesToKey;
     /**
      * Saves an item to the activity's key-value store.
      *
@@ -1308,6 +1760,7 @@ declare class Game implements Activity {
     storeItemExists(key: string, globalStore?: boolean): Promise<boolean>;
     get dataStores(): IDataStore[];
     set dataStores(dataStores: IDataStore[]);
+    hasDataStores(): boolean;
     private getLocalizationOptionsFromGameParameters;
     private isLocalizationRequested;
     setParameters(additionalParameters: unknown): void;
@@ -1627,7 +2080,23 @@ declare class Game implements Activity {
      * @param plugin - Plugin to register
      */
     registerPlugin(plugin: Plugin): Promise<void>;
+    /**
+     * Updates active scenes and executes plugins.
+     *
+     */
     private update;
+    /**
+     * Updates all active scenes and their children.
+     */
+    private updateScenes;
+    /**
+     * Executes all active plugins before scenes are updated.
+     */
+    private executeBeforeUpdatePlugins;
+    /**
+     * Executes all active plugins after scenes have been updated.
+     */
+    private executeAfterUpdatePlugins;
     private draw;
     private calculateFps;
     private takeCurrentSceneSnapshot;
@@ -1789,7 +2258,7 @@ declare abstract class M2Node implements M2NodeOptions {
     _scale: number;
     alpha: number;
     _zRotation: number;
-    isUserInteractionEnabled: boolean;
+    protected _isUserInteractionEnabled: boolean;
     draggable: boolean;
     hidden: boolean;
     layout: Layout;
@@ -1803,7 +2272,6 @@ declare abstract class M2Node implements M2NodeOptions {
     absoluteAlphaChange: number;
     actions: Action[];
     queuedAction?: Action;
-    originalActions: Action[];
     eventListeners: M2NodeEventListener<M2NodeEvent>[];
     readonly uuid: string;
     needsInitialization: boolean;
@@ -2092,6 +2560,8 @@ declare abstract class M2Node implements M2NodeOptions {
     set zRotation(zRotation: number);
     get scale(): number;
     set scale(scale: number);
+    get isUserInteractionEnabled(): boolean;
+    set isUserInteractionEnabled(isUserInteractionEnabled: boolean);
     /**
      * For a given directed acyclic graph, topological ordering of the vertices will be identified using BFS
      * @param adjList Adjacency List that represent a graph with vertices and edges
@@ -2155,8 +2625,27 @@ interface RotateActionOptions {
     runDuringTransition?: boolean;
 }
 
-interface IActionContainer {
-    children?: Array<Action>;
+interface PlayActionOptions {
+    /** Should the action run during screen transitions? Default is no */
+    runDuringTransition?: boolean;
+}
+
+/**
+ * An ActionContainer is an Action that can contain other actions.
+ *
+ * @remarks An ActionContainer is a parent action that can have other
+ * actions as children. The `Sequence`, `Group`, `Repeat,` and
+ * `RepeatForever` actions implement `ActionContainer`.
+ */
+interface ActionContainer extends Action {
+    /**
+     * Immediate children of a parent action.
+     */
+    children: Array<Action>;
+    /**
+     * All children of a parent action and those children's children, recursively.
+     */
+    descendants: Array<Action>;
 }
 
 /** The type of action */
@@ -2168,7 +2657,140 @@ declare enum ActionType {
     Move = "Move",
     Scale = "Scale",
     FadeAlpha = "FadeAlpha",
-    Rotate = "Rotate"
+    Rotate = "Rotate",
+    Play = "Play",
+    Repeat = "Repeat",
+    RepeatForever = "RepeatForever"
+}
+
+/**
+ * A class for for working with numeric values that may be currently unknown,
+ * but may be known in the future.
+ *
+ * @remarks Most m2c2kit actions have a known duration, such as waiting for a
+ * given duration or moving a node to a specific position across a specific
+ * duration: the duration is explicitly provided when the `Action` is created.
+ * However, some actions have a duration that is not known when the `Action` is
+ * created, but it will be known in the future. So far, the only action that
+ * requires this is the `play` action. In the browser, a sound file cannot be
+ * decoded by the `AudioContext` interface (which will calculate the duration)
+ * until the user has interacted with the page, which could be after the
+ * `Action` has been created. This is a problem because a `sequence` action
+ * needs to know the duration of all its children in order to calculate its own
+ * duration and when each of the child actions will start. To solve this
+ * problem, the `Futurable` class is a simple implementation of the Composite
+ * pattern that allows for the creation of a numeric value that may be known in
+ * the future. If a value is not known at creation time, it is represented by
+ * `Infinity`. The `Futurable` class supports addition and subtraction of
+ * another `Futurable` and numbers. When the numeric value of a `Futurable` is
+ * requested, it evaluates the expression and returns the numeric value. If any
+ * of the terms in the expression is a `Futurable`, it will recursively
+ * evaluate them. If any of the terms are unknown (represented by `Infinity`),
+ * it will return `Infinity`. If a previous unknown value becomes known, any
+ * other `Futurable` that depends on it will also become known.
+ */
+declare class Futurable {
+    /** The numbers, operators, and other Futurables that represent a value. */
+    private expression;
+    /** Log a warning to console if a expression is this length. */
+    private readonly WARNING_EXPRESSION_LENGTH;
+    constructor(value?: Futurable | number);
+    /**
+     * Appends a number or another Futurable to this Futurable's expression.
+     *
+     * @remarks This method does a simple array push, but checks the length of
+     * the expression array and warns if it gets "too long." This may indicate
+     * a logic error, unintended recursion, etc. because our use cases will
+     * likely not have expressions that are longer than
+     * `Futural.WARNING_EXPRESSION_LENGTH` elements.
+     *
+     * @param value - value to add to the expression.
+     */
+    private pushToExpression;
+    /**
+     * Assigns a value, either known or Futurable, to this Futurable.
+     *
+     * @remarks This method clears the current expression.
+     *
+     * @param value - value to assign to this Futurable.
+     */
+    assign(value: number | Futurable): void;
+    /**
+     * Performs addition on this Futurable.
+     *
+     * @remarks This method modifies the Futurable by adding the term(s) to the
+     * Futurable's expression.
+     *
+     * @param terms - terms to add to this Futurable.
+     * @returns the modified Futurable.
+     */
+    add(...terms: Array<Futurable | number>): this;
+    /**
+     * Performs subtraction on this Futurable.
+     *
+     * @remarks This method modifies the Futurable by subtracting the term(s)
+     * from the Futurable's expression.
+     *
+     * @param terms - terms to subtract from this Futurable.
+     * @returns the modified Futurable.
+     */
+    subtract(...terms: Array<Futurable | number>): this;
+    /**
+     * Adds an operation (an operator and term(s)) to the Futurable's
+     * expression.
+     *
+     * @param operator - Add or Subtract.
+     * @param terms - terms to add to the expression.
+     */
+    private appendOperation;
+    /**
+     * Gets the numeric value of this Futurable.
+     *
+     * @remarks This method evaluates the expression of the Futurable and
+     * returns the numeric value. If any of the terms in the expression are
+     * Futurables, it will recursively evaluate them. If any of the terms are
+     * unknown (represented by Infinity), it will return Infinity.
+     *
+     * @returns the numeric value of this Futurable.
+     */
+    get value(): number;
+}
+
+/**
+ * An extension of `ActionContainer` that can repeat another action.
+ *
+ * @remarks A `RepeatingActionContainer` is a parent action that repeats
+ * another action for a specified number of repetitions, as provided in the
+ * `count` property. The `Repeat` and `RepeatForever` actions implement
+ * `RepeatingActionContainer`.
+ */
+interface RepeatingActionContainer extends ActionContainer {
+    /** Number of times the action will repeat. */
+    count: number;
+    /** Number of completions done. */
+    completedRepetitions: number;
+    /** How long, in milliseconds, the repeating action has run. This is updated
+     * only at the end of a repetition. */
+    cumulativeDuration: number;
+    /** Returns true when the action is running and the action's children have
+     * just completed a repetition */
+    repetitionHasCompleted: boolean;
+}
+
+interface RepeatActionOptions {
+    /** Action to repeat */
+    action: Action;
+    /** Number of times to repeat the action */
+    count: number;
+    /** Should the action run during screen transitions? Default is no */
+    runDuringTransition?: boolean;
+}
+
+interface RepeatForeverActionOptions {
+    /** Action to repeat */
+    action: Action;
+    /** Should the action run during screen transitions? Default is no */
+    runDuringTransition?: boolean;
 }
 
 /**
@@ -2177,151 +2799,362 @@ declare enum ActionType {
  */
 declare abstract class Action {
     abstract type: ActionType;
-    startOffset: number;
-    endOffset: number;
+    startOffset: Futurable;
     started: boolean;
     running: boolean;
-    completed: boolean;
+    private _completed;
+    /**
+     * Start time of a running action is always known; it is not a `Futurable`.
+     * -1 indicates that the root action has not yet started running.
+     */
     runStartTime: number;
-    duration: number;
+    duration: Futurable;
     runDuringTransition: boolean;
-    parent?: Action;
-    isParent: boolean;
-    isChild: boolean;
+    parent?: ActionContainer;
     key?: string;
     constructor(runDuringTransition?: boolean);
+    /**
+     * Prepares the Action for evaluation.
+     *
+     * @remarks Calculates start times for all actions in the hierarchy
+     * and returns a copy of the action that is prepared for evaluation during
+     * the update loop.
+     *
+     * @param key - optional string to identify an action
+     * @returns action prepared for evaluation
+     */
+    initialize(key?: string): Action;
+    /**
+     * Clones the action, and any actions it contains, recursively.
+     *
+     * @remarks We need to clone an action before running it because actions
+     * have state that is updated over time such as whether they are running or
+     * not, etc. If we didn't clone actions, two nodes reusing the same action
+     * would share state. On `Action`, this method is abstract and is
+     * implemented in each subclass.
+     *
+     * @returns a clone of the action
+     */
+    abstract clone(): Action;
+    /**
+     * Parses the action hierarchy and assigns each action its parent and
+     * root action.
+     *
+     * @remarks Uses recursion to handle arbitrary level of nesting parent
+     * actions within parent actions. When this method is called from the
+     * `initialize()` method, the root action is both the `action` and the
+     * `rootAction`. This is because the action is the top-level action in the
+     * hierarchy. When the method calls itself recursively, the `rootAction`
+     * remains the same, but the `action` is a child action or the action of a
+     * repeating action.
+     *
+     * @param action - the action to assign parents to
+     * @param rootAction - top-level action passed to the run method
+     * @param key - optional string to identify an action. The key is assigned
+     * to every action in the hierarchy.
+     */
+    private assignParents;
+    /**
+     * Sets the runDuringTransition property based on descendants.
+     *
+     * @remarks This ensures that a parent action has its `runDuringTransition`
+     * property set to true if any of its descendants have their
+     * `runDuringTransition` property set to true. Parent actions do not have a
+     * way for the user to set this property directly; it is inferred (propagated
+     * up) from the descendants.
+     *
+     * @param action to propagate runDuringTransition property to
+     */
+    private propagateRunDuringTransition;
+    /**
+     * Assigns durations to all actions in the hierarchy.
+     *
+     * @remarks Uses recursion to handle arbitrary level of nesting parent
+     * actions within parent actions.
+     *
+     * @param action - the action to assign durations to
+     */
+    private assignDurations;
+    /**
+     * Calculates the duration of an action, including any children actions
+     * the action may contain.
+     *
+     * @remarks Uses recursion to handle arbitrary level of nesting parent
+     * actions within parent actions
+     *
+     * @param action
+     * @returns the calculated duration
+     */
+    private calculateDuration;
+    /**
+     * Assigns start offsets to all actions in the hierarchy.
+     *
+     * @remarks Uses recursion to handle arbitrary level of nesting parent
+     * actions within parent actions.
+     *
+     * @param action - the action to assign start offsets to
+     */
+    private assignStartOffsets;
+    /**
+     * Calculates the start offset. This is when an action should start,
+     * relative to the start time of its parent (if it has a parent).
+     *
+     * @param action - the action to calculate the start offset for
+     * @returns the start offset as a Futurable
+     */
+    private calculateStartOffset;
+    /**
+     * Evaluates an action, updating the node's properties as needed.
+     *
+     * @remarks This method is called every frame by the M2Node's `update()`
+     * method.
+     *
+     * @param action - the Action to be evaluated and possibly run
+     * @param node - the `M2Node` that the action will be run on
+     * @param now - the current elapsed time, from `performance.now()`
+     * @param dt - the time since the last frame (delta time)
+     */
+    static evaluateAction(action: Action, node: M2Node, now: number, dt: number): void;
+    private static evaluateRepeatingActions;
+    private static evaluateRotateAction;
+    private static evaluateFadeAlphaAction;
+    private static evaluateScaleAction;
+    private static evaluateMoveAction;
+    private static evaluateWaitAction;
+    private static evaluatePlayAction;
+    private static evaluateCustomAction;
+    /**
+     * Assigns RunStartTime to all actions in the hierarchy.
+     *
+     * @remarks Uses recursion to handle arbitrary level of nesting parent
+     * actions within parent actions.
+     *
+     * @param action - the action to assign RunStartTime to
+     */
+    assignRunStartTimes(action: Action, runStartTime: number): void;
+    /**
+     * Configures action to be run again.
+     *
+     * @remarks This method is called on a repeating action's children when they
+     * need to be run again.
+     *
+     * @param action - action to restart
+     * @param now - current time
+     */
+    restartAction(action: Action, now: number): void;
+    /**
+     * Determines if the action should be running.
+     *
+     * @remarks An action should be running if current time is in the interval
+     * [ start time + start offset, start time + start offset + duration ]
+     *
+     * @param now - current time
+     * @returns true if the action should be running
+     */
+    shouldBeRunning(now: number): boolean;
     /**
      * Creates an action that will move a node to a point on the screen.
      *
      * @param options - {@link MoveActionOptions}
      * @returns The move action
      */
-    static move(options: MoveActionOptions): Action;
+    static move(options: MoveActionOptions): MoveAction;
     /**
-     * Creates an action that will wait a given duration before it is considered complete.
+     * Creates an action that will wait a given duration before it is considered
+     * complete.
      *
      * @param options - {@link WaitActionOptions}
      * @returns The wait action
      */
-    static wait(options: WaitActionOptions): Action;
+    static wait(options: WaitActionOptions): WaitAction;
     /**
      * Creates an action that will execute a callback function.
      *
      * @param options - {@link CustomActionOptions}
      * @returns The custom action
      */
-    static custom(options: CustomActionOptions): Action;
+    static custom(options: CustomActionOptions): CustomAction;
+    /**
+     * Creates an action that will play a sound.
+     *
+     * @remarks This action can only be used with a SoundPlayer node.
+     * It will throw an error if used with any other node type.
+     *
+     * @param options - {@link PlayActionOptions}
+     * @returns The play action
+     */
+    static play(options?: PlayActionOptions): PlayAction;
     /**
      * Creates an action that will scale the node's size.
      *
-     * @remarks Scaling is relative to any inherited scaling, which is multiplicative. For example, if the node's parent is scaled to 2.0 and this node's action scales to 3.0, then the node will appear 6 times as large as original.
+     * @remarks Scaling is relative to any inherited scaling, which is
+     * multiplicative. For example, if the node's parent is scaled to 2.0 and
+     * this node's action scales to 3.0, then the node will appear 6 times as
+     * large as original.
      *
      * @param options - {@link ScaleActionOptions}
      * @returns The scale action
      */
-    static scale(options: ScaleActionOptions): Action;
+    static scale(options: ScaleActionOptions): ScaleAction;
     /**
      * Creates an action that will change the node's alpha (opacity).
      *
-     * @remarks Alpha has multiplicative inheritance. For example, if the node's parent is alpha .5 and this node's action fades alpha to .4, then the node will appear with alpha .2.
+     * @remarks Alpha has multiplicative inheritance. For example, if the node's
+     * parent is alpha .5 and this node's action fades alpha to .4, then the
+     * node will appear with alpha .2.
      *
      * @param options - {@link FadeAlphaActionOptions}
      * @returns The fadeAlpha action
      */
-    static fadeAlpha(options: FadeAlphaActionOptions): Action;
+    static fadeAlpha(options: FadeAlphaActionOptions): FadeAlphaAction;
     /**
      * Creates an action that will rotate the node.
      *
-     * @remarks Rotate actions are applied to their children. In addition to this node's rotate action, all ancestors' rotate actions will also be applied.
+     * @remarks Rotate actions are applied to their children. In addition to this
+     * node's rotate action, all ancestors' rotate actions will also be applied.
      *
      * @param options - {@link RotateActionOptions}
      * @returns The rotate action
      */
-    static rotate(options: RotateActionOptions): Action;
+    static rotate(options: RotateActionOptions): RotateAction;
     /**
      * Creates an array of actions that will be run in order.
      *
-     * @remarks The next action will not begin until the current one has finished. The sequence will be considered completed when the last action has completed.
+     * @remarks The next action will not begin until the current one has
+     * finished. The sequence will be considered completed when the last action
+     * has completed.
      *
      * @param actions - One or more actions that form the sequence
      * @returns
      */
-    static sequence(actions: Array<Action>): Action;
+    static sequence(actions: Array<Action>): SequenceAction;
     /**
      * Create an array of actions that will be run simultaneously.
      *
-     * @remarks All actions within the group will begin to run at the same time. The group will be considered completed when the longest-running action has completed.
+     * @remarks All actions within the group will begin to run at the same time.
+     * The group will be considered completed when the longest-running action
+     * has completed.
      *
      * @param actions - One or more actions that form the group
      * @returns
      */
-    static group(actions: Array<Action>): Action;
-    initialize(node: M2Node, key?: string): Array<Action>;
-    static cloneAction(action: Action, key?: string): Action;
-    static evaluateAction(action: Action, node: M2Node, now: number, dt: number): void;
+    static group(actions: Array<Action>): GroupAction;
     /**
-     * Calculates the duration of an action, including any children actions
-     * the action may contain.
-     *
-     * @remarks Uses recursion to handle arbitrary level of nesting parent
-     * actions within parent actions
+     * Creates an action that will repeat another action a given number of times.
      *
-     * @param action
-     * @returns the calculated duration
+     * @param options - {@link RepeatActionOptions}
+     * @returns The repeat action
      */
-    private calculateDuration;
+    static repeat(options: RepeatActionOptions): RepeatAction;
     /**
-     * Update each action's start and end offsets.
+     * Creates an action that will repeat another action forever.
      *
-     * @remarks Uses recursion to handle arbitrary level of nesting parent
-     * actions within parent actions.
+     * @remarks A repeat forever action is a special case of a repeat action
+     * where the count is set to infinity.
      *
-     * @param action that needs assigning start and end offsets
+     * @param options - {@link RepeatForeverActionOptions}
+     * @returns The repeat forever action
      */
-    private calculateStartEndOffsets;
+    static repeatForever(options: RepeatForeverActionOptions): RepeatForeverAction;
     /**
-     * Takes an action hierarchy and flattens to an array of non-nested actions
+     * Type guard that returns true if the action is a parent action.
      *
-     * @remarks Uses recursion to handle arbitrary level of nesting parent
-     * actions within parent actions
+     * @remarks Parent actions are Group, Sequence, Repeat, and RepeatForever
+     * actions.
      *
-     * @param action - the action to flatten
-     * @param actions - the accumulator array of flattened actions. This will be
-     * undefined on the first call, and an array on recursive calls
-     * @returns flattened array of actions
+     * @param action - action to check
+     * @returns true if the action is a parent action
      */
-    private flattenActions;
+    isParent(action: Action): action is ActionContainer;
     /**
-     * Parses the action hierarchy and assigns each action its parent and
-     * root action.
+     * Type guard that returns true if the action can repeat.
      *
-     * @remarks Uses recursion to handle arbitrary level of nesting parent
-     * actions within parent actions
+     * @remarks Repeating actions are Repeat and RepeatForever actions.
      *
-     * @param action
-     * @param rootAction - top-level action passed to the run method
-     * @param key - optional string to identify an action
+     * @param action - action to check
+     * @returns true if the action is a RepeatAction or RepeatForeverAction
      */
-    private assignParents;
+    private isRepeating;
+    /**
+     * Indicates whether the action has completed.
+     */
+    get completed(): boolean;
+    set completed(value: boolean);
 }
-declare class SequenceAction extends Action implements IActionContainer {
+declare class SequenceAction extends Action implements ActionContainer {
     type: ActionType;
     children: Array<Action>;
     constructor(actions: Array<Action>);
+    clone(): SequenceAction;
+    /**
+     * Indicates whether the action has completed, taking into account all its
+     * child actions.
+     *
+     * @remarks Is read-only for parent actions.
+     */
+    get completed(): boolean;
+    get descendants(): Action[];
 }
-declare class GroupAction extends Action implements IActionContainer {
+declare class GroupAction extends Action implements ActionContainer {
     type: ActionType;
     children: Action[];
     constructor(actions: Array<Action>);
+    clone(): GroupAction;
+    /**
+     * Indicates whether the action has completed, taking into account all its
+     * child actions.
+     *
+     * @remarks Is read-only for parent actions.
+     */
+    get completed(): boolean;
+    get descendants(): Action[];
+}
+declare class RepeatAction extends Action implements RepeatingActionContainer {
+    type: ActionType;
+    count: number;
+    children: Array<Action>;
+    completedRepetitions: number;
+    cumulativeDuration: number;
+    constructor(action: Action, count: number, runDuringTransition?: boolean);
+    clone(): RepeatAction;
+    /**
+     * Indicates whether the action has completed, taking into account all its
+     * child actions and the number of repetitions.
+     *
+     * @remarks Is read-only for parent actions.
+     */
+    get completed(): boolean;
+    get descendantsAreCompleted(): boolean;
+    /**
+     * Indicates whether a single repetition of a repeating action has just
+     * completed.
+     *
+     * @returns returns true if a repetition has completed
+     */
+    get repetitionHasCompleted(): boolean;
+    get descendants(): Action[];
+}
+declare class RepeatForeverAction extends RepeatAction {
+    type: ActionType;
+    count: number;
+    constructor(action: Action, runDuringTransition?: boolean);
+    clone(): RepeatForeverAction;
 }
 declare class CustomAction extends Action {
     type: ActionType;
     callback: () => void;
     constructor(callback: () => void, runDuringTransition?: boolean);
+    clone(): CustomAction;
+}
+declare class PlayAction extends Action {
+    type: ActionType;
+    constructor(runDuringTransition?: boolean);
+    clone(): PlayAction;
 }
 declare class WaitAction extends Action {
     type: ActionType;
-    constructor(duration: number, runDuringTransition: boolean);
+    constructor(duration: Futurable, runDuringTransition: boolean);
+    clone(): WaitAction;
 }
 declare class MoveAction extends Action {
     type: ActionType;
@@ -2330,19 +3163,22 @@ declare class MoveAction extends Action {
     dx: number;
     dy: number;
     easing: EasingFunction;
-    constructor(point: Point, duration: number, easing: EasingFunction, runDuringTransition: boolean);
+    constructor(point: Point, duration: Futurable, easing: EasingFunction, runDuringTransition: boolean);
+    clone(): MoveAction;
 }
 declare class ScaleAction extends Action {
     type: ActionType;
     scale: number;
     delta: number;
-    constructor(scale: number, duration: number, runDuringTransition?: boolean);
+    constructor(scale: number, duration: Futurable, runDuringTransition?: boolean);
+    clone(): ScaleAction;
 }
 declare class FadeAlphaAction extends Action {
     type: ActionType;
     alpha: number;
     delta: number;
-    constructor(alpha: number, duration: number, runDuringTransition?: boolean);
+    constructor(alpha: number, duration: Futurable, runDuringTransition?: boolean);
+    clone(): FadeAlphaAction;
 }
 declare class RotateAction extends Action {
     type: ActionType;
@@ -2351,7 +3187,8 @@ declare class RotateAction extends Action {
     shortestUnitArc?: boolean;
     delta: number;
     finalValue: number;
-    constructor(byAngle: number | undefined, toAngle: number | undefined, shortestUnitArc: boolean | undefined, duration: number, runDuringTransition?: boolean);
+    constructor(byAngle: number | undefined, toAngle: number | undefined, shortestUnitArc: boolean | undefined, duration: Futurable, runDuringTransition?: boolean);
+    clone(): RotateAction;
 }
 
 interface ActivityCallbacks {
@@ -2760,6 +3597,8 @@ interface IText {
     fontName?: string;
     fontColor?: RgbaColor;
     fontSize?: number;
+    interpolation?: StringInterpolationMap;
+    localize?: boolean;
 }
 
 declare enum LabelHorizontalAlignmentMode {
@@ -2793,15 +3632,18 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     private _fontNames;
     private _fontColor;
     private _fontSize;
+    private _interpolation;
     private _horizontalAlignmentMode;
     private _preferredMaxLayoutWidth;
     private _backgroundColor?;
+    private _localize;
     private paragraph?;
     private paraStyle?;
     private builder?;
     private _fontPaint?;
     private _backgroundPaint?;
-    private _translatedText;
+    private localizedFontName;
+    private localizedFontNames;
     /**
      * Single or multi-line text formatted and rendered on the screen.
      *
@@ -2825,7 +3667,8 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     dispose(): void;
     get text(): string;
     set text(text: string);
-    get translatedText(): string;
+    get interpolation(): StringInterpolationMap;
+    set interpolation(interpolation: StringInterpolationMap);
     get fontName(): string | undefined;
     set fontName(fontName: string | undefined);
     get fontNames(): Array<string> | undefined;
@@ -2840,6 +3683,8 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     set preferredMaxLayoutWidth(preferredMaxLayoutWidth: number | undefined);
     get backgroundColor(): RgbaColor | undefined;
     set backgroundColor(backgroundColor: RgbaColor | undefined);
+    get localize(): boolean;
+    set localize(localize: boolean);
     private get backgroundPaint();
     private set backgroundPaint(value);
     private get fontPaint();
@@ -3213,6 +4058,131 @@ declare class Shape extends M2Node implements IDrawable, ShapeOptions {
     set strokeColorPaintNotAntialiased(value: Paint);
 }
 
+interface SoundPlayerOptions extends M2NodeOptions {
+    /** Name of sound to play. Must have been previously loaded */
+    soundName: string;
+}
+
+declare class SoundPlayer extends M2Node implements SoundPlayerOptions {
+    readonly type = M2NodeType.SoundPlayer;
+    isDrawable: boolean;
+    soundName: string;
+    /**
+     * Node for playing sounds.
+     *
+     * @param options - {@link SoundPlayerOptions}
+     */
+    constructor(options: SoundPlayerOptions);
+    initialize(): void;
+    dispose(): void;
+    /**
+     * Duplicates a node using deep copy.
+     *
+     * @remarks This is a deep recursive clone (node and children).
+     * The uuid property of all duplicated nodes will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated node. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): SoundPlayer;
+}
+
+interface SoundRecorderOptions extends M2NodeOptions {
+    /** Preferred MIME type to use for recording audio. `audio/webm` or `audio/mp4` is recommended. If omitted, it will use any MIME type supported by the device. */
+    mimeType?: string;
+    /** Additional MIME types to use for recording audio, in order of preference, if preferred type is not supported. `["audio/webm", "audio/mp4"]` is recommended. */
+    backupMimeTypes?: Array<string>;
+    /** Maximum duration, in milliseconds, to allow recording. If recording lasts longer than this duration, it will automatically be paused. This can be used to prevent excessively long recording and memory usage. */
+    maximumDuration?: number;
+    /** Additional audio constraints to be applied when requesting the audio device.
+     * see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+     * @remarks Use with caution. All kinds of constraints may not be supported
+     * on all browsers, and specifying too restrictive constraints will result in
+     * no available user audio device and an exception. Unusual constraints may
+     * also result in an unexpected device being selected.
+     * @example
+     *  audioTrackConstraints: {
+     *    channelCount: 1,
+     *    noiseSuppression: { ideal: true },
+     *  }
+     * */
+    audioTrackConstraints?: MediaTrackConstraints;
+}
+
+interface SoundRecorderResults {
+    /** The MIME type of the recorded audio, possibly including the codec. */
+    mimeType: string;
+    /** The ISO 8601 device timestamp when the recording began. */
+    beginIso8601Timestamp: string;
+    /** The ISO 8601 device timestamp when the recording ended. */
+    endIso8601Timestamp: string;
+    /** The duration of the recording in milliseconds. @remarks The duration may be different from the timestamp end minus begin times if the recording was paused. */
+    duration: number;
+    /** The settings of the audio tracks when the recording began. */
+    audioTrackSettings?: Array<MediaTrackSettings>;
+    /** The recorded audio as a base 64 string. */
+    audioBase64: string;
+    /** The recorded audio as a Blob. */
+    audioBlob: Blob;
+}
+
+declare class SoundRecorder extends M2Node implements Omit<SoundRecorderOptions, "backupMimeTypes"> {
+    readonly type = M2NodeType.SoundRecorder;
+    isDrawable: boolean;
+    mimeType?: string;
+    audioTrackConstraints?: MediaTrackConstraints;
+    maximumDuration?: number;
+    private _isRecording;
+    private _isPaused;
+    private mediaRecorder?;
+    private audioChunks;
+    private mediaTrackSettings?;
+    private beginIso8601Timestamp?;
+    private endIso8601Timestamp?;
+    private timerUuid;
+    /**
+     * Node for recording sounds.
+     *
+     * @param options - {@link SoundRecorderOptions}
+     */
+    constructor(options?: SoundRecorderOptions);
+    initialize(): void;
+    start(): Promise<void>;
+    stop(): Promise<SoundRecorderResults>;
+    pause(): void;
+    resume(): void;
+    /** Is the `SoundRecorder` currently recording? */
+    get isRecording(): boolean;
+    /** Is the `SoundRecorder` currently paused? */
+    get isPaused(): boolean;
+    update(): void;
+    /**
+     * Returns an array of supported audio MIME types for MediaRecorder.
+     *
+     * @remarks Adapted from https://stackoverflow.com/a/68236494
+     * License: https://creativecommons.org/licenses/by-sa/4.0/
+     *
+     * @returns
+     */
+    private getMediaRecorderSupportedAudioMimeTypes;
+    private blobToBase64;
+    private getMimeTypeWithoutCodecs;
+    private getSupportedBackupMimeType;
+    dispose(): void;
+    /**
+     * Duplicates a node using deep copy.
+     *
+     * @remarks This is a deep recursive clone (node and children).
+     * The uuid property of all duplicated nodes will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated node. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): SoundRecorder;
+}
+
 interface SpriteOptions extends M2NodeOptions, DrawableOptions {
     /** Name of image to use for sprite. Must have been previously loaded */
     imageName?: string;
@@ -3257,6 +4227,18 @@ declare class Sprite extends M2Node implements IDrawable, SpriteOptions {
     update(): void;
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
+    /**
+     * Draws a rectangle border around the image to indicate that a fallback
+     * image is being used.
+     *
+     * @remarks The size of the rectangle is the same as the image, but because
+     * the stroke width of the paint is wider than 1 pixel (see method
+     * `configureImageLocalization()` in `ImageManager.ts`), the rectangle will
+     * be larger than the image and thus be visible.
+     *
+     * @param canvas - CanvasKit canvas to draw on
+     */
+    private drawFallbackImageBorder;
 }
 
 interface StoryOptions {
@@ -3284,11 +4266,16 @@ declare class TextLine extends M2Node implements IDrawable, IText, TextLineOptio
     private _fontName;
     private _fontColor;
     private _fontSize;
+    private _interpolation;
+    private _localize;
     private paint?;
     private font?;
     private typeface;
-    private _translatedText;
-    private missingTranslationPaint?;
+    private tryMissingTranslationPaint;
+    private textForDraw;
+    private fontForDraw?;
+    private localizedFontName;
+    private localizedFontNames;
     /**
      * Single-line text rendered on the screen.
      *
@@ -3297,16 +4284,6 @@ declare class TextLine extends M2Node implements IDrawable, IText, TextLineOptio
      * @param options - {@link TextLineOptions}
      */
     constructor(options?: TextLineOptions);
-    get text(): string;
-    set text(text: string);
-    get translatedText(): string;
-    get fontName(): string | undefined;
-    set fontName(fontName: string | undefined);
-    get fontColor(): RgbaColor;
-    set fontColor(fontColor: RgbaColor);
-    get fontSize(): number;
-    set fontSize(fontSize: number);
-    update(): void;
     initialize(): void;
     /**
      * Determines the M2Font object that needs to be ready in order to draw
@@ -3319,6 +4296,20 @@ declare class TextLine extends M2Node implements IDrawable, IText, TextLineOptio
      * @returns a M2Font object that is required for the TextLine
      */
     private getRequiredTextLineFont;
+    private createFontPaint;
+    private createFont;
+    get text(): string;
+    set text(text: string);
+    get fontName(): string | undefined;
+    set fontName(fontName: string | undefined);
+    get fontColor(): RgbaColor;
+    set fontColor(fontColor: RgbaColor);
+    get fontSize(): number;
+    set fontSize(fontSize: number);
+    get interpolation(): StringInterpolationMap;
+    set interpolation(interpolation: StringInterpolationMap);
+    get localize(): boolean;
+    set localize(localize: boolean);
     dispose(): void;
     /**
      * Duplicates a node using deep copy.
@@ -3331,6 +4322,7 @@ declare class TextLine extends M2Node implements IDrawable, IText, TextLineOptio
      * provided, name will be the new uuid
      */
     duplicate(newName?: string): TextLine;
+    update(): void;
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
 }
@@ -3447,6 +4439,15 @@ declare class Timer {
 
 declare class Uuid {
     static generate(): string;
+    /**
+     * Tests if a string is a valid UUID.
+     *
+     * @remarks Will match UUID versions 1 through 8, plus the nil UUID.
+     *
+     * @param uuid - the string to test
+     * @returns true if the string is a valid UUID
+     */
+    static isValid(uuid: string | undefined | null): boolean;
 }
 
 declare class WebColors {
@@ -3611,4 +4612,4 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-export { Action, type Activity, type ActivityCallbacks, type ActivityEvent, type ActivityEventListener, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DrawableOptions, type EasingFunction, Easings, Equals, FadeAlphaAction, type FadeAlphaActionOptions, type FontAsset, type FontData, FontManager, Game, type GameData, type GameEvent, type GameOptions, type GameParameters, GlobalVariables, GroupAction, I18n, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LegacyTimer, type M2ColorfulPath, type M2DragEvent, type M2Event, type M2EventListener, M2EventType, type M2Image, M2ImageStatus, M2Node, type M2NodeEvent, type M2NodeEventListener, type M2NodeOptions, M2NodeType, type M2Path, type M2PointerEvent, M2c2KitHelpers, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, type Plugin, type PluginEvent, type Point, RandomDraws, type RectOptions, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, SceneTransition, SequenceAction, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, Sprite, type SpriteOptions, Story, type StoryOptions, type TapEvent, TextLine, type TextLineOptions, type TextOptions, Timer, Transition, TransitionDirection, TransitionType, type Translations, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };
+export { Action, type Activity, type ActivityCallbacks, type ActivityEvent, type ActivityEventListener, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DrawableOptions, type EasingFunction, Easings, Equals, FadeAlphaAction, type FadeAlphaActionOptions, type FontAsset, type FontData, FontManager, Game, type GameData, type GameEvent, type GameOptions, type GameParameters, GlobalVariables, GroupAction, I18n, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LegacyTimer, type LocaleSvg, type M2ColorfulPath, type M2DragEvent, type M2Event, type M2EventListener, M2EventType, type M2Image, M2ImageStatus, M2Node, type M2NodeEvent, type M2NodeEventListener, type M2NodeOptions, M2NodeType, type M2Path, type M2PointerEvent, type M2Sound, M2SoundStatus, M2c2KitHelpers, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, PlayAction, type PlayActionOptions, type Plugin, type PluginEvent, type Point, RandomDraws, type RectOptions, RepeatAction, RepeatForeverAction, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, SceneTransition, SequenceAction, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, type SoundAsset, SoundManager, SoundPlayer, type SoundPlayerOptions, SoundRecorder, type SoundRecorderOptions, type SoundRecorderResults, Sprite, type SpriteOptions, Story, type StoryOptions, type StringInterpolationMap, type TapEvent, type TextAndFont, TextLine, type TextLineOptions, type TextLocalizationResult, type TextOptions, type TextWithFontCustomization, Timer, Transition, TransitionDirection, TransitionType, type Translation, type TranslationConfiguration, type TranslationOptions, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };