@rive-app/canvas-single 2.38.4 → 2.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rive-app/canvas-single",
-  "version": "2.38.4",
+  "version": "2.39.0",
   "description": "Rive's high-level canvas based web api all in one js file.",
   "main": "rive.js",
   "homepage": "https://rive.app",

package/rive.d.ts

@@ -1,8 +1,11 @@
 import * as rc from "./rive_advanced.mjs";
 import { RuntimeLoader, type RuntimeCallback } from "./runtimeLoader";
+import { SemanticTreeModel, AccessibilityOverlay, SemanticMode, type RiveSemanticsOptions } from "./semantics";
 import { ImageWrapper, AudioWrapper, FontWrapper, RiveFont as RiveFontClassUtil } from "./utils";
 export type AssetLoadCallback = (asset: rc.FileAsset, bytes: Uint8Array) => boolean;
 export { RiveFontClassUtil as RiveFont };
+export { SemanticMode };
+export type { RiveSemanticsOptions };
 export type { FileAsset, AudioAsset, FontAsset, ImageAsset, } from "./rive_advanced.mjs";
 /**
  * Generic type for a parameterless void callback
@@ -243,6 +246,19 @@ export interface RiveParameters {
      * enabled by default.
      */
     enableRiveAssetCDN?: boolean;
+    /**
+     * @experimental This API is early and may encounter breaking behavior change without a major version bump
+     *
+     * When to build semantic trees and the accessibility DOM overlay.
+     * Defaults to {@link SemanticMode.Disabled}.
+     */
+    semanticsMode?: SemanticMode;
+    /**
+     * @experimental This API is early and may encounter breaking behavior change without a major version bump
+     *
+     * Optional options for the accessibility overlay container.
+     */
+    semanticsOptions?: RiveSemanticsOptions;
     /**
      * Turn off Rive Listeners. This means state machines that have Listeners
      * will not be invoked, and also, no event listeners pertaining to Listeners
@@ -340,6 +356,8 @@ export interface RiveLoadParameters {
     useOffscreenRenderer?: boolean;
     shouldDisableRiveListeners?: boolean;
     tabIndex?: number;
+    semanticsMode?: SemanticMode;
+    semanticsOptions?: RiveSemanticsOptions;
 }
 export interface RiveResetParameters {
     artboard?: string;
@@ -418,6 +436,10 @@ export declare class RiveFile implements rc.FinalizableTarget {
     getDefaultBindableArtboard(): BindableArtboard | null;
     internalBindableArtboardFromArtboard(artboard: rc.Artboard): BindableArtboard | null;
     viewModelByName(name: string): ViewModel | null;
+    /**
+     * @returns the names of the file's global view models, in file order.
+     */
+    globalViewModelNames(): string[];
 }
 export declare class Rive {
     private readonly canvas;
@@ -453,6 +475,10 @@ export declare class Rive {
     private dispatchPointerExit;
     private enableMultiTouch;
     private enableRiveAssetCDN;
+    private semanticsMode;
+    private semanticsOptions;
+    /** True when this instance may drain semantics and render the overlay. */
+    private _semanticsActive;
     private _volume;
     private _artboardWidth;
     private _artboardHeight;
@@ -466,10 +492,21 @@ export declare class Rive {
     private _pageVisibilityHandler;
     private _explicitlyStoppedRendering;
     private _viewModelInstance;
+    private _globalViewModelInstances;
     private _dataEnums;
     private _tabIndex;
     private _prevHasFocus;
     private _focusOptions;
+    private _semanticTree;
+    private _accessibilityOverlay;
+    /**
+     * True when an input to the accessibility overlay's artboard→canvas transform
+     * (layout fit/alignment/bounds, devicePixelRatio, or layout scale) has changed
+     * and the matrix must be recomputed on the next overlay update. Avoids calling
+     * computeAlignment every frame when only the semantic tree changed.
+     */
+    private _overlayTransformDirty;
+    private readonly _instanceId;
     private drawOptimization;
     private enablePerfMarks;
     durations: number[];
@@ -479,6 +516,21 @@ export declare class Rive {
     constructor(params: RiveParameters);
     get viewModelCount(): number;
     static new(params: RiveParameters): Rive;
+    /**
+     * @experimental Turns on semantics and the accessibility overlay for this
+     * instance. Idempotent; safe to call before or after load. Use this to drive
+     * a consumer-controlled accessibility toggle when constructed with the
+     * default {@link SemanticMode.Disabled}.
+     */
+    enableSemantics(): void;
+    private activateSemantics;
+    private syncSemanticsOnStateMachines;
+    /**
+     * Tears down the semantic tree and accessibility overlay. The overlay captures the
+     * active state machine in its action closures, so it must not outlive the
+     * instances it points at (reset/load delete them)
+     */
+    private cleanupSemantics;
     private onSystemAudioChanged;
     private onCanvasResize;
     private init;
@@ -489,6 +541,11 @@ export declare class Rive {
      * i.e. { isTouchScrollEnabled: true }
      */
     setupRiveListeners(riveListenerOptions?: SetupRiveListenersOptions): void;
+    /**
+     * Wire keyboard interactions when a playing state machine has focus nodes.
+     * Called at listener setup and lazily each frame so late-bound bindable artboards work.
+     */
+    private ensureKeyboardInteractions;
     private cleanupKeyboardInteractions;
     /**
      * Remove Rive Listeners setup on the canvas
@@ -621,6 +678,18 @@ export declare class Rive {
      * Returns the name of the active artboard
      */
     get activeArtboard(): string;
+    /**
+     * Returns the semantic tree model when semantics are enabled, or null.
+     * The overlay and external consumers use this to inspect the
+     * current state of the semantic tree.
+     */
+    get semanticTree(): SemanticTreeModel | null;
+    /**
+     * Returns the accessibility overlay when semantics are enabled, or null.
+     * External consumers can use this to inspect the
+     * current state of the accessibility overlay for this instance.
+     */
+    get accessibilityOverlay(): AccessibilityOverlay | null;
     get animationNames(): string[];
     /**
      * Returns a list of state machine names from the current artboard
@@ -830,10 +899,47 @@ export declare class Rive {
     get devicePixelRatioUsed(): number;
     set devicePixelRatioUsed(value: number);
     /**
-     * Initialize the data context with the view model instance.
+     * Sets the main view model instance and applies it (rebinds). Equivalent to
+     * `setViewModelInstance(vmi)` followed by `bind()`.
      */
     bindViewModelInstance(viewModelInstance: ViewModelInstance | null): void;
+    /**
+     * Sets the main view model instance in the data context WITHOUT rebinding.
+     * Call {@link bind} to apply. Use this with {@link setGlobalViewModelInstance}
+     * to batch multiple changes into a single rebind.
+     */
+    setViewModelInstance(viewModelInstance: ViewModelInstance | null): void;
+    /**
+     * Applies any pending `set*` view model instance changes by rebinding the
+     * data binds once.
+     * Implicitly creates and binds any view models that have not been set.
+     */
+    bind(): void;
     get viewModelInstance(): ViewModelInstance | null;
+    /**
+     * Sets (or replaces) the global view model instance for the given global view
+     * model name in the data context WITHOUT rebinding. The main instance and any
+     * other globals keep their order. Call {@link bind} to apply — batch several
+     * `set*` calls then a single `bind()` to avoid rebinding per set.
+     * @param name - the name of the global view model
+     * @param viewModelInstance - the instance to set for that global
+     * @returns whether the instance was set (false if `name` does not match a
+     * global view model in the file)
+     */
+    setGlobalViewModelInstance(name: string, viewModelInstance: ViewModelInstance): boolean;
+    /**
+     * @param name - the name of the global view model
+     * @returns the global view model instance bound under the given name — the
+     * instance set via {@link setGlobalViewModelInstance} or one created by
+     * auto-bind — or null if none has been set/created for that name (globals are
+     * not auto-created; the getter never creates one).
+     */
+    globalViewModelInstance(name: string): ViewModelInstance | null;
+    /**
+     * @returns the names of the file's global view models, in file order. Use
+     * these with {@link setGlobalViewModelInstance} / {@link globalViewModelInstance}.
+     */
+    globalViewModelNames(): string[];
     viewModelByIndex(index: number): ViewModel | null;
     viewModelByName(name: string): ViewModel | null;
     enums(): DataEnum[];
@@ -957,6 +1063,12 @@ export declare class ViewModelInstance {
      * @param path - path to the image property
      */
     image(path: string): ViewModelInstanceAssetImage | null;
+    /**
+     * method to access a view model property instance belonging
+     * to the view model instance or to a nested view model instance
+     * @param path - path to the font property
+     */
+    font(path: string): ViewModelInstanceAssetFont | null;
     /**
      * method to access an artboard property instance belonging
      * to the view model instance or to a nested view model instance
@@ -1058,6 +1170,11 @@ export declare class ViewModelInstanceAssetImage extends ViewModelInstanceValue
     set value(image: rc.Image | null);
     internalHandleCallback(callback: Function): void;
 }
+export declare class ViewModelInstanceAssetFont extends ViewModelInstanceValue {
+    constructor(instance: rc.ViewModelInstanceAssetFont, root: ViewModelInstance);
+    set value(font: rc.Font | null);
+    internalHandleCallback(callback: Function): void;
+}
 export declare class ViewModelInstanceArtboard extends ViewModelInstanceValue {
     constructor(instance: rc.ViewModelInstanceArtboard, root: ViewModelInstance);
     set value(artboard: BaseArtboard | null);