@rive-app/canvas-lite 2.37.7 → 2.38.0

package/rive.js

@@ -2546,7 +2546,7 @@ moduleRtn = da;
 /* 5 */
 /***/ ((module) => {
 
-module.exports = /*#__PURE__*/JSON.parse('{"name":"@rive-app/canvas-lite","version":"2.37.7","description":"A lite version of Rive\'s canvas based web api.","main":"rive.js","homepage":"https://rive.app","repository":{"type":"git","url":"https://github.com/rive-app/rive-wasm/tree/master/js"},"keywords":["rive","animation"],"author":"Rive","contributors":["Luigi Rosso <luigi@rive.app> (https://rive.app)","Maxwell Talbot <max@rive.app> (https://rive.app)","Arthur Vivian <arthur@rive.app> (https://rive.app)","Umberto Sonnino <umberto@rive.app> (https://rive.app)","Matthew Sullivan <matt.j.sullivan@gmail.com> (mailto:matt.j.sullivan@gmail.com)"],"license":"MIT","files":["rive.js","rive.js.map","rive.wasm","rive_fallback.wasm","rive.d.ts","rive_advanced.mjs.d.ts","runtimeLoader.d.ts","utils"],"typings":"rive.d.ts","dependencies":{},"browser":{"fs":false,"path":false}}');
+module.exports = /*#__PURE__*/JSON.parse('{"name":"@rive-app/canvas-lite","version":"2.38.0","description":"A lite version of Rive\'s canvas based web api.","main":"rive.js","homepage":"https://rive.app","repository":{"type":"git","url":"https://github.com/rive-app/rive-wasm/tree/master/js"},"keywords":["rive","animation"],"author":"Rive","contributors":["Luigi Rosso <luigi@rive.app> (https://rive.app)","Maxwell Talbot <max@rive.app> (https://rive.app)","Arthur Vivian <arthur@rive.app> (https://rive.app)","Umberto Sonnino <umberto@rive.app> (https://rive.app)","Matthew Sullivan <matt.j.sullivan@gmail.com> (mailto:matt.j.sullivan@gmail.com)"],"license":"MIT","files":["rive.js","rive.js.map","rive.wasm","rive_fallback.wasm","rive.d.ts","rive_advanced.mjs.d.ts","runtimeLoader.d.ts","utils"],"typings":"rive.d.ts","dependencies":{},"browser":{"fs":false,"path":false}}');
 
 /***/ }),
 /* 6 */
@@ -2554,26 +2554,30 @@ module.exports = /*#__PURE__*/JSON.parse('{"name":"@rive-app/canvas-lite","versi
 
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   AudioAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.AudioAssetWrapper),
-/* harmony export */   AudioWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.AudioWrapper),
-/* harmony export */   BLANK_URL: () => (/* reexport safe */ _sanitizeUrl__WEBPACK_IMPORTED_MODULE_1__.BLANK_URL),
-/* harmony export */   CustomFileAssetLoaderWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.CustomFileAssetLoaderWrapper),
-/* harmony export */   FileAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.FileAssetWrapper),
-/* harmony export */   FileFinalizer: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.FileFinalizer),
-/* harmony export */   FontAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.FontAssetWrapper),
-/* harmony export */   FontWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.FontWrapper),
-/* harmony export */   ImageAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.ImageAssetWrapper),
-/* harmony export */   ImageWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.ImageWrapper),
-/* harmony export */   RiveFont: () => (/* reexport safe */ _riveFont__WEBPACK_IMPORTED_MODULE_3__.RiveFont),
-/* harmony export */   createFinalization: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.createFinalization),
-/* harmony export */   finalizationRegistry: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__.finalizationRegistry),
+/* harmony export */   AudioAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.AudioAssetWrapper),
+/* harmony export */   AudioWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.AudioWrapper),
+/* harmony export */   BLANK_URL: () => (/* reexport safe */ _sanitizeUrl__WEBPACK_IMPORTED_MODULE_2__.BLANK_URL),
+/* harmony export */   CustomFileAssetLoaderWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.CustomFileAssetLoaderWrapper),
+/* harmony export */   FileAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.FileAssetWrapper),
+/* harmony export */   FileFinalizer: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.FileFinalizer),
+/* harmony export */   FocusSessionState: () => (/* reexport safe */ _registerKeyboardInteractions__WEBPACK_IMPORTED_MODULE_1__.FocusSessionState),
+/* harmony export */   FontAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.FontAssetWrapper),
+/* harmony export */   FontWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.FontWrapper),
+/* harmony export */   ImageAssetWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.ImageAssetWrapper),
+/* harmony export */   ImageWrapper: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.ImageWrapper),
+/* harmony export */   KeyboardInteractions: () => (/* reexport safe */ _registerKeyboardInteractions__WEBPACK_IMPORTED_MODULE_1__.KeyboardInteractions),
+/* harmony export */   RiveFont: () => (/* reexport safe */ _riveFont__WEBPACK_IMPORTED_MODULE_4__.RiveFont),
+/* harmony export */   createFinalization: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.createFinalization),
+/* harmony export */   finalizationRegistry: () => (/* reexport safe */ _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__.finalizationRegistry),
 /* harmony export */   registerTouchInteractions: () => (/* reexport safe */ _registerTouchInteractions__WEBPACK_IMPORTED_MODULE_0__.registerTouchInteractions),
-/* harmony export */   sanitizeUrl: () => (/* reexport safe */ _sanitizeUrl__WEBPACK_IMPORTED_MODULE_1__.sanitizeUrl)
+/* harmony export */   sanitizeUrl: () => (/* reexport safe */ _sanitizeUrl__WEBPACK_IMPORTED_MODULE_2__.sanitizeUrl)
 /* harmony export */ });
 /* harmony import */ var _registerTouchInteractions__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(7);
-/* harmony import */ var _sanitizeUrl__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(8);
-/* harmony import */ var _finalizationRegistry__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(9);
-/* harmony import */ var _riveFont__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(10);
+/* harmony import */ var _registerKeyboardInteractions__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(8);
+/* harmony import */ var _sanitizeUrl__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(9);
+/* harmony import */ var _finalizationRegistry__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(10);
+/* harmony import */ var _riveFont__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(11);
+
 
 
 
@@ -2660,7 +2664,7 @@ var getClientCoordinates = function (event, isTouchScrollEnabled, enableMultiTou
  * the state machine pointer move/up/down functions based on cursor interaction
  */
 var registerTouchInteractions = function (_a) {
-    var canvas = _a.canvas, artboard = _a.artboard, _b = _a.stateMachines, stateMachines = _b === void 0 ? [] : _b, renderer = _a.renderer, rive = _a.rive, fit = _a.fit, alignment = _a.alignment, _c = _a.isTouchScrollEnabled, isTouchScrollEnabled = _c === void 0 ? false : _c, _d = _a.dispatchPointerExit, dispatchPointerExit = _d === void 0 ? true : _d, _e = _a.enableMultiTouch, enableMultiTouch = _e === void 0 ? false : _e, _f = _a.layoutScaleFactor, layoutScaleFactor = _f === void 0 ? 1.0 : _f;
+    var canvas = _a.canvas, artboard = _a.artboard, _b = _a.stateMachines, stateMachines = _b === void 0 ? [] : _b, renderer = _a.renderer, rive = _a.rive, fit = _a.fit, alignment = _a.alignment, _c = _a.isTouchScrollEnabled, isTouchScrollEnabled = _c === void 0 ? false : _c, _d = _a.dispatchPointerExit, dispatchPointerExit = _d === void 0 ? true : _d, _e = _a.enableMultiTouch, enableMultiTouch = _e === void 0 ? false : _e, _f = _a.layoutScaleFactor, layoutScaleFactor = _f === void 0 ? 1.0 : _f, advanceAndDrain = _a.advanceAndDrain;
     if (!canvas ||
         !stateMachines.length ||
         !renderer ||
@@ -2803,6 +2807,8 @@ var registerTouchInteractions = function (_a) {
                     var stateMachine = stateMachines_3[_c];
                     _loop_3(stateMachine);
                 }
+                // Advance the state machine immediately so pointer down(s) takes effect synchronously
+                advanceAndDrain(0);
                 break;
             }
             // Pointer click released on the canvas
@@ -2817,6 +2823,8 @@ var registerTouchInteractions = function (_a) {
                     var stateMachine = stateMachines_4[_d];
                     _loop_4(stateMachine);
                 }
+                // Advance the state machine immediately so pointer up(s) takes effect synchronously
+                advanceAndDrain(0);
                 // Release the primary touch lock once that finger lifts so the next
                 // touchstart can claim a new primary finger.
                 if (!enableMultiTouch &&
@@ -2835,6 +2843,8 @@ var registerTouchInteractions = function (_a) {
                     var stateMachine = stateMachines_5[_e];
                     _loop_5(stateMachine);
                 }
+                // Advance the state machine immediately so pointer up(s) takes effect synchronously
+                advanceAndDrain(0);
                 break;
             }
             default:
@@ -2875,6 +2885,153 @@ var registerTouchInteractions = function (_a) {
 /* 8 */
 /***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
 
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   FocusSessionState: () => (/* binding */ FocusSessionState),
+/* harmony export */   KeyboardInteractions: () => (/* binding */ KeyboardInteractions)
+/* harmony export */ });
+/**
+ * Tracks the relationship between the canvas's DOM focus and Rive's internal focus for the
+ * current focus session.
+ *
+ * NotFocused   — the canvas is not the active DOM element, or Rive entered and then released focus
+ *                internally this session. Either way the next Tab should move on to the next page
+ *                element, so Tab events are ignored.
+ * EntryPending — the canvas has DOM focus but Rive holds no active focus node yet, and the next Tab should enter
+ *                the focus tree. This is the resting state for pointer-driven focus (a click on the
+ *                canvas), or an edge case for keyboard focus where initial focus action did not land on a focus node.
+ * RiveFocused  — a Rive node currently holds focus. Tab/Shift+Tab are routed to the Rive focus
+ *                manager and trapped inside the canvas until Rive notifies focus has ended.
+ *
+ * When keyboard focus lands on the canvas, onCanvasFocus reads the direction focus came from and
+ * moves into the focus tree immediately, going straight to RiveFocused. EntryPending is only set via pointer focus (or keyboard focus
+ * where focusNext()/focusPrevious() return false but respects tabindex).
+ */
+var FocusSessionState;
+(function (FocusSessionState) {
+    FocusSessionState["NotFocused"] = "notFocused";
+    FocusSessionState["EntryPending"] = "entryPending";
+    FocusSessionState["RiveFocused"] = "riveFocused";
+})(FocusSessionState || (FocusSessionState = {}));
+/**
+ * Manages keyboard and DOM focus interactions for a Rive canvas.
+ *
+ * Tracks the canvas focus session state (focusSessionState) and routes
+ * Tab/Shift+Tab to the Rive state machine's focus manager. Exposes shared
+ * state as properties so the Rive render loop can read them directly.
+ */
+var KeyboardInteractions = /** @class */ (function () {
+    function KeyboardInteractions(_a) {
+        var canvas = _a.canvas, stateMachine = _a.stateMachine, hasFocusNodes = _a.hasFocusNodes;
+        var _this = this;
+        this.focusSessionState = FocusSessionState.NotFocused;
+        /**
+         * Handles the canvas gaining browser focus. The behavior differs based on how focus was gained -
+         *
+         * Pointer-driven focus: the canvas now has focus but Rive holds nothing yet, so we move to EntryPending — this lets the
+         * next Tab enter the focus tree even when the focus is pointer-driven
+         *
+         * Keyboard-driven focus: we enter the Rive focus tree immediately once canvas gains focus.
+         * The direction is inferred from where focus came from: an element before the canvas in DOM order
+         * means a forward Tab (focusNext), one after means a Shift+Tab (focusPrevious). :focus-visible
+         * gates this so a click doesn't yank Rive focus to the first node on the focus event itself.
+         */
+        this.onCanvasFocus = function (event) {
+            if (!_this.hasFocusNodes)
+                return;
+            if (_this.mainSm.focusState().hasFocus)
+                return;
+            _this.focusSessionState = FocusSessionState.EntryPending;
+            // Pointer focus waits for the user's next Tab (handled in onKeyDown). Keyboard focus enters now.
+            if (!_this.isKeyboardDrivenFocus())
+                return;
+            var forward = _this.cameFromBeforeCanvas(event.relatedTarget);
+            if (forward ? _this.mainSm.focusNext() : _this.mainSm.focusPrevious()) {
+                _this.focusSessionState = FocusSessionState.RiveFocused;
+            }
+        };
+        this.onCanvasBlur = function (_event) {
+            _this.focusSessionState = FocusSessionState.NotFocused;
+        };
+        this.onKeyDown = function (event) {
+            if (_this.focusSessionState === FocusSessionState.NotFocused)
+                return;
+            if (event.code === "Tab" && _this.hasFocusNodes) {
+                var forward = !event.shiftKey;
+                var focusMoved = forward ? _this.mainSm.focusNext() : _this.mainSm.focusPrevious();
+                if (focusMoved) {
+                    // A Rive node accepted focus — keep trapping Tab inside the canvas.
+                    _this.focusSessionState = FocusSessionState.RiveFocused;
+                    event.preventDefault();
+                }
+                else {
+                    // No more traversable nodes — release Tab to the page.
+                    // Set state immediately; onCanvasBlur will also fire naturally.
+                    _this.focusSessionState = FocusSessionState.NotFocused;
+                }
+            }
+        };
+        this.canvas = canvas;
+        this.mainSm = stateMachine;
+        this.hasFocusNodes = hasFocusNodes;
+        canvas.addEventListener("focus", this.onCanvasFocus);
+        canvas.addEventListener("blur", this.onCanvasBlur);
+        canvas.addEventListener("keydown", this.onKeyDown);
+    }
+    /**
+     * Set the FocusSessionState. Useful for invoking a Rive "blur" without actually blurring from the <canvas>. This
+     * helps put the DOM focus state on the canvas rather than the <body>, so the user doesn't lose the spot in page navigation
+     *
+     * @param state FocusSessionState enum
+     */
+    KeyboardInteractions.prototype.setFocusSessionState = function (state) {
+        this.focusSessionState = state;
+    };
+    /**
+     * Called by pollFocusState on the Rive instance when it observes hasFocus=true. Rive acquired
+     * focus internally (e.g. via a listener action or state transition) without a DOM focus event,
+     * so mark the session RiveFocused.
+     */
+    KeyboardInteractions.prototype.notifyRiveFocused = function () {
+        this.focusSessionState = FocusSessionState.RiveFocused;
+    };
+    /**
+     * Whether the canvas currently matches :focus-visible — the browser's heuristic for keyboard-
+     * (vs pointer-) driven focus. For older browser versions that don't support this selector, return false
+     * so that we don't incorrectly assume pointer vs keyboard focus. Next tab would enter the focus tree in those edge cases.
+     */
+    KeyboardInteractions.prototype.isKeyboardDrivenFocus = function () {
+        try {
+            return this.canvas.matches(":focus-visible");
+        }
+        catch (_a) {
+            return false;
+        }
+    };
+    KeyboardInteractions.prototype.cameFromBeforeCanvas = function (from) {
+        if (!from)
+            return true;
+        var position = this.canvas.compareDocumentPosition(from);
+        if (position & Node.DOCUMENT_POSITION_PRECEDING)
+            return true;
+        if (position & Node.DOCUMENT_POSITION_FOLLOWING)
+            return false;
+        return true;
+    };
+    KeyboardInteractions.prototype.cleanup = function () {
+        this.canvas.removeEventListener("focus", this.onCanvasFocus);
+        this.canvas.removeEventListener("blur", this.onCanvasBlur);
+        this.canvas.removeEventListener("keydown", this.onKeyDown);
+    };
+    return KeyboardInteractions;
+}());
+
+
+
+/***/ }),
+/* 9 */
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   BLANK_URL: () => (/* binding */ BLANK_URL),
@@ -2925,7 +3082,7 @@ function sanitizeUrl(url) {
 
 
 /***/ }),
-/* 9 */
+/* 10 */
 /***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
 
 __webpack_require__.r(__webpack_exports__);
@@ -3066,6 +3223,9 @@ var CustomFileAssetLoaderWrapper = /** @class */ (function () {
         else if (asset.isFont) {
             assetWrapper = new FontAssetWrapper(asset);
         }
+        else {
+            return false;
+        }
         return this._assetLoaderCallback(assetWrapper, bytes);
     };
     return CustomFileAssetLoaderWrapper;
@@ -3204,7 +3364,7 @@ var createFinalization = function (target, finalizable) {
 
 
 /***/ }),
-/* 10 */
+/* 11 */
 /***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
 
 __webpack_require__.r(__webpack_exports__);
@@ -3705,6 +3865,7 @@ var StateMachine = /** @class */ (function () {
         this.inputs = [];
         this.instance = new runtime.StateMachineInstance(stateMachine, artboard);
         this.initInputs(runtime);
+        this.hasFocusNodes = this.instance.hasFocusNodes();
     }
     Object.defineProperty(StateMachine.prototype, "name", {
         get: function () {
@@ -3800,6 +3961,19 @@ var StateMachine = /** @class */ (function () {
             this.instance.bindViewModelInstance(viewModelInstance.runtimeInstance);
         }
     };
+    /**
+     * Get metadata about the state of focus if applicable for this state machine.
+     * @returns FocusState - { hasFocus: boolean, expectsKeyboardInput: boolean }
+     */
+    StateMachine.prototype.focusState = function () {
+        return this.instance.focusState();
+    };
+    /**
+     * Clear focus from the Rive focus node tree.
+     */
+    StateMachine.prototype.clearFocus = function () {
+        this.instance.clearFocus();
+    };
     return StateMachine;
 }());
 // #endregion
@@ -4806,7 +4980,7 @@ var RiveFile = /** @class */ (function () {
 var Rive = /** @class */ (function () {
     function Rive(params) {
         var _this = this;
-        var _a, _b;
+        var _a, _b, _c;
         // Tracks if a Rive file is loaded
         this.loaded = false;
         // Tracks if a Rive file is destroyed
@@ -4823,8 +4997,10 @@ var Rive = /** @class */ (function () {
         this.readyForPlaying = false;
         // Runtime artboard
         this.artboard = null;
-        // place to clear up event listeners
+        // place to clear up pointer/touch event listeners
         this.eventCleanup = null;
+        // Manages keyboard and DOM-focus interactions for the canvas.
+        this._keyboardInteractions = null;
         this.shouldDisableRiveListeners = false;
         this.automaticallyHandleEvents = false;
         this.dispatchPointerExit = true;
@@ -4852,8 +5028,20 @@ var Rive = /** @class */ (function () {
         this._audioEventListener = null;
         // draw method bound to the class
         this._boundDraw = null;
+        // Page visibility handler — prevents state machine advancing / rAF from being invoked with large time delta
+        // when the browser tab is switched back to after being hidden.
+        this._pageVisibilityHandler = null;
+        // True only when the page visibility handler itself cancelled an active frame.
+        // Set by stopRendering(), cleared by startRendering(). Prevents the
+        // visibilitychange handler from restarting a rendering loop the caller intentionally stopped.
+        this._explicitlyStoppedRendering = false;
         this._viewModelInstance = null;
         this._dataEnums = null;
+        this._tabIndex = null;
+        this._prevHasFocus = false;
+        this._focusOptions = {
+            allowFocusInterrupt: false,
+        };
         this.drawOptimization = DrawOptimizationOptions.DrawOnChanged;
         // When true, emits performance.mark/measure entries for load and render.
         this.enablePerfMarks = false;
@@ -4874,12 +5062,18 @@ var Rive = /** @class */ (function () {
                 _this.resizeToCanvas();
             }
         };
+        // Tracks the current animation frame request
+        this.frameRequestId = null;
         /**
          * Used be draw to track when a second of active rendering time has passed.
          * Used for debugging purposes
          */
         this.renderSecondTimer = 0;
         this._boundDraw = this.draw.bind(this);
+        if (typeof document !== 'undefined') {
+            this._pageVisibilityHandler = this._onPageVisibilityChange.bind(this);
+            document.addEventListener('visibilitychange', this._pageVisibilityHandler);
+        }
         this.canvas = params.canvas;
         if (params.canvas.constructor === HTMLCanvasElement) {
             this._observed = observers.add(this.canvas, this.onCanvasResize);
@@ -4906,6 +5100,7 @@ var Rive = /** @class */ (function () {
         this.enablePerfMarks = !!params.enablePerfMarks;
         if (this.enablePerfMarks)
             _runtimeLoader__WEBPACK_IMPORTED_MODULE_1__.RuntimeLoader.enablePerfMarks = true;
+        this._focusOptions = (_c = params.focusOptions) !== null && _c !== void 0 ? _c : this._focusOptions;
         // New event management system
         this.eventManager = new EventManager();
         if (params.onLoad)
@@ -4958,6 +5153,7 @@ var Rive = /** @class */ (function () {
             stateMachines: params.stateMachines,
             artboard: params.artboard,
             useOffscreenRenderer: params.useOffscreenRenderer,
+            tabIndex: params.tabIndex,
         });
     }
     Object.defineProperty(Rive.prototype, "viewModelCount", {
@@ -4979,13 +5175,14 @@ var Rive = /** @class */ (function () {
     // Initializes the Rive object either from constructor or load()
     Rive.prototype.init = function (_a) {
         var _this = this;
-        var src = _a.src, buffer = _a.buffer, riveFile = _a.riveFile, animations = _a.animations, stateMachines = _a.stateMachines, artboard = _a.artboard, _b = _a.autoplay, autoplay = _b === void 0 ? false : _b, _c = _a.useOffscreenRenderer, useOffscreenRenderer = _c === void 0 ? false : _c, _d = _a.autoBind, autoBind = _d === void 0 ? false : _d;
+        var src = _a.src, buffer = _a.buffer, riveFile = _a.riveFile, animations = _a.animations, stateMachines = _a.stateMachines, artboard = _a.artboard, _b = _a.autoplay, autoplay = _b === void 0 ? false : _b, _c = _a.useOffscreenRenderer, useOffscreenRenderer = _c === void 0 ? false : _c, _d = _a.autoBind, autoBind = _d === void 0 ? false : _d, tabIndex = _a.tabIndex;
         if (this.destroyed) {
             return;
         }
         this.src = src;
         this.buffer = buffer;
         this.riveFile = riveFile;
+        this._tabIndex = tabIndex !== null && tabIndex !== void 0 ? tabIndex : null;
         // If no source file url specified, it's a bust
         if (!this.src && !this.buffer && !this.riveFile) {
             throw new RiveError(Rive.missingErrorMessage);
@@ -5056,9 +5253,11 @@ var Rive = /** @class */ (function () {
         if (this.eventCleanup) {
             this.eventCleanup();
         }
+        this.cleanupKeyboardInteractions();
         if (!this.shouldDisableRiveListeners) {
-            var activeStateMachines = (this.animator.stateMachines || [])
-                .filter(function (sm) { return sm.playing && _this.runtime.hasListeners(sm.instance); })
+            var playingStateMachines = this.animator.stateMachines.filter(function (sm) { return sm.playing; });
+            var activeStateMachines = playingStateMachines
+                .filter(function (sm) { return _this.runtime.hasListeners(sm.instance); })
                 .map(function (sm) { return sm.instance; });
             var touchScrollEnabledOption = this.isTouchScrollEnabled;
             var dispatchPointerExit = this.dispatchPointerExit;
@@ -5079,7 +5278,34 @@ var Rive = /** @class */ (function () {
                 dispatchPointerExit: dispatchPointerExit,
                 enableMultiTouch: enableMultiTouch,
                 layoutScaleFactor: this._layout.layoutScaleFactor,
+                advanceAndDrain: this.advanceAndReportChanges.bind(this)
             });
+            // Wire up keyboard interactions for state machines that have focus nodes.
+            //   hasFocusNodes — unified focus tree check, gates tab traversal
+            var smWithFocusNodes = playingStateMachines.filter(function (sm) { return sm.hasFocusNodes; });
+            if (smWithFocusNodes.length) {
+                // Set the canvas as a tabbable element if there are any focus nodes.
+                // Prefer the tabIndex param set by the user, otherwise use 0.
+                // But do not override any explicit tabIndex already set on the canvas, if any.
+                var currentCanvasTabIndex = this.canvas.tabIndex;
+                // By default, canvas elements have a tabIndex of -1
+                if (currentCanvasTabIndex === -1 || isNaN(currentCanvasTabIndex)) {
+                    this.canvas.tabIndex = (this._tabIndex !== null ? this._tabIndex : 0);
+                }
+                if (typeof window !== "undefined") {
+                    this._keyboardInteractions = new _utils__WEBPACK_IMPORTED_MODULE_2__.KeyboardInteractions({
+                        canvas: this.canvas,
+                        stateMachine: smWithFocusNodes[0].instance, // work off assumption of single state machine
+                        hasFocusNodes: true,
+                    });
+                }
+            }
+        }
+    };
+    Rive.prototype.cleanupKeyboardInteractions = function () {
+        if (this._keyboardInteractions) {
+            this._keyboardInteractions.cleanup();
+            this._keyboardInteractions = null;
         }
     };
     /**
@@ -5090,6 +5316,7 @@ var Rive = /** @class */ (function () {
             this.eventCleanup();
             this.eventCleanup = null;
         }
+        this.cleanupKeyboardInteractions();
     };
     /**
      * If the instance has audio and the system audio is not ready
@@ -5267,27 +5494,53 @@ var Rive = /** @class */ (function () {
         return changed;
     };
     /**
-     * Draw rendering loop; renders animation frames at the correct time interval.
-     * @param time the time at which to render a frame
+     * Poll focus state each frame to see if we should focus/blur the canvas in case
+     * Rive internally updated focus outside of user interaction (e.g., via listener action)
      */
-    Rive.prototype.draw = function (time, onSecond) {
-        var _a;
-        // Clear the frameRequestId, as we're now rendering a fresh frame
-        this.frameRequestId = null;
-        var before = performance.now();
-        // On the first pass, make sure lastTime has a valid value
-        if (!this.lastRenderTime) {
-            this.lastRenderTime = time;
+    Rive.prototype.pollFocusState = function () {
+        if (!this._keyboardInteractions) {
+            this._prevHasFocus = false;
+            return;
         }
-        // Handle the onSecond callback
-        this.renderSecondTimer += time - this.lastRenderTime;
-        if (this.renderSecondTimer > 5000) {
-            this.renderSecondTimer = 0;
-            onSecond === null || onSecond === void 0 ? void 0 : onSecond();
+        var activeSm = this.animator.stateMachines.find(function (sm) { return sm.playing && sm.hasFocusNodes; }); // work off assumption of single state machine
+        if (!activeSm) {
+            this._prevHasFocus = false;
+            return;
         }
-        // Calculate the elapsed time between frames in seconds
-        var elapsedTime = (time - this.lastRenderTime) / 1000;
-        this.lastRenderTime = time;
+        if (this.canvas instanceof HTMLCanvasElement) {
+            var hasFocus = activeSm.focusState().hasFocus;
+            if (hasFocus) {
+                // Rive has an active focus node. Mark the session RiveFocused so Tab stays
+                // trapped and a later internal release (hasFocus true → false) is detected.
+                this._keyboardInteractions.notifyRiveFocused();
+                // Only steal DOM focus on the false→true transition. If hasFocus stays
+                // true across frames and the user clicks away, do not re-focus the canvas again.
+                if (!this._prevHasFocus) {
+                    if (this.canvas !== document.activeElement && this._focusOptions.allowFocusInterrupt) {
+                        this.canvas.focus();
+                    }
+                    this._prevHasFocus = true;
+                }
+                return;
+            }
+            this._prevHasFocus = false;
+            // hasFocus is false — only act when Rive previously held focus and released it internally
+            // (state change clears focus). Release the DOM Tab trap so the next Tab moves to the next
+            // page element. EntryPending and NotFocused cases are intentional no-ops — EntryPending in
+            // particular must stay in its state (a click awaiting its first Tab) rather than be reset here.
+            if (this._keyboardInteractions.focusSessionState === _utils__WEBPACK_IMPORTED_MODULE_2__.FocusSessionState.RiveFocused) {
+                this._keyboardInteractions.setFocusSessionState(_utils__WEBPACK_IMPORTED_MODULE_2__.FocusSessionState.NotFocused);
+            }
+        }
+    };
+    /**
+     * Handles important sequence of reporting Rive events, advancing the state machine or animation, and invoking various callbacks
+     * due to state changes, view model property changes, etc.
+     *
+     * @param elapsedTime time to advance the state machine by
+     */
+    Rive.prototype.advanceAndReportChanges = function (elapsedTime) {
+        var _a;
         // - Advance non-paused animations by the elapsed number of seconds
         // - Advance any animations that require scrubbing
         // - Advance to the first frame even when autoplay is false
@@ -5351,13 +5604,48 @@ var Rive = /** @class */ (function () {
                 performance.mark("rive:sm-advance:end:f".concat(_perfFrame));
                 performance.measure("rive:sm-advance:f".concat(_perfFrame), "rive:sm-advance:start:f".concat(_perfFrame), "rive:sm-advance:end:f".concat(_perfFrame));
             }
-            // stateMachine.instance.apply(this.artboard);
         }
-        // Once the animations have been applied to the artboard, advance it
+        // For linear animations that have been applied to the artboard, advance it
         // by the elapsed time.
         if (this.animator.stateMachines.length == 0) {
             this.artboard.advance(elapsedTime);
         }
+        // Check for any animations that looped
+        this.animator.handleLooping();
+        // Check for any state machines that had a state change
+        this.animator.handleStateChanges();
+        // Report advanced time
+        this.animator.handleAdvancing(elapsedTime);
+        // Poll focus state to see whether or not to blur or pull up a virtual keyboard for any change to a text input node.
+        this.pollFocusState();
+        // Handle callbacks for view model property changes
+        (_a = this._viewModelInstance) === null || _a === void 0 ? void 0 : _a.handleCallbacks();
+    };
+    /**
+     * Draw rendering loop; renders animation frames at the correct time interval.
+     * @param time the time at which to render a frame
+     */
+    Rive.prototype.draw = function (time, onSecond) {
+        // Clear the frameRequestId, as we're now rendering a fresh frame
+        this.frameRequestId = null;
+        var before = performance.now();
+        // Instrument the first 3 frames so the Performance timeline shows precise
+        // per-call latency for advance, draw, and flush without polluting the trace.
+        var _perfFrame = this.enablePerfMarks && this.frameCount < 3 ? this.frameCount : -1;
+        // On the first pass, make sure lastTime has a valid value
+        if (!this.lastRenderTime) {
+            this.lastRenderTime = time;
+        }
+        // Handle the onSecond callback
+        this.renderSecondTimer += time - this.lastRenderTime;
+        if (this.renderSecondTimer > 5000) {
+            this.renderSecondTimer = 0;
+            onSecond === null || onSecond === void 0 ? void 0 : onSecond();
+        }
+        // Calculate the elapsed time between frames in seconds
+        var elapsedTime = (time - this.lastRenderTime) / 1000;
+        this.lastRenderTime = time;
+        this.advanceAndReportChanges(elapsedTime);
         var renderer = this.renderer;
         // Do not draw on 0 canvas size
         if (!this._hasZeroSize) {
@@ -5395,12 +5683,6 @@ var Rive = /** @class */ (function () {
                 this._needsRedraw = false;
             }
         }
-        // Check for any animations that looped
-        this.animator.handleLooping();
-        // Check for any state machines that had a state change
-        this.animator.handleStateChanges();
-        // Report advanced time
-        this.animator.handleAdvancing(elapsedTime);
         // Add duration to create frame to durations array
         this.frameCount++;
         var after = performance.now();
@@ -5410,7 +5692,6 @@ var Rive = /** @class */ (function () {
             this.frameTimes.shift();
             this.durations.shift();
         }
-        (_a = this._viewModelInstance) === null || _a === void 0 ? void 0 : _a.handleCallbacks();
         // Calling requestAnimationFrame will rerun draw() at the correct rate:
         // https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations
         if (this.animator.isPlaying) {
@@ -5489,6 +5770,10 @@ var Rive = /** @class */ (function () {
             audioManager.remove(this._audioEventListener);
             this._audioEventListener = null;
         }
+        if (this._pageVisibilityHandler) {
+            document.removeEventListener('visibilitychange', this._pageVisibilityHandler);
+            this._pageVisibilityHandler = null;
+        }
         (_b = this._viewModelInstance) === null || _b === void 0 ? void 0 : _b.cleanup();
         this._viewModelInstance = null;
         this._dataEnums = null;
@@ -5513,6 +5798,7 @@ var Rive = /** @class */ (function () {
         if (this.eventCleanup !== null) {
             this.eventCleanup();
         }
+        this.cleanupKeyboardInteractions();
         // Delete all animation and state machine instances
         this.stop();
         if (this.artboard) {
@@ -5581,6 +5867,7 @@ var Rive = /** @class */ (function () {
         if (this.eventCleanup) {
             this.eventCleanup();
         }
+        this.cleanupKeyboardInteractions();
         this.setupRiveListeners();
         this.startRendering();
     };
@@ -5598,6 +5885,7 @@ var Rive = /** @class */ (function () {
         if (this.eventCleanup) {
             this.eventCleanup();
         }
+        this.cleanupKeyboardInteractions();
         this.animator.pause(animationNames);
     };
     Rive.prototype.scrub = function (animationNames, value) {
@@ -5633,6 +5921,7 @@ var Rive = /** @class */ (function () {
         if (this.eventCleanup) {
             this.eventCleanup();
         }
+        this.cleanupKeyboardInteractions();
     };
     /**
      * Resets the animation
@@ -6092,6 +6381,7 @@ var Rive = /** @class */ (function () {
      * they would have been at if rendering had not been stopped.
      */
     Rive.prototype.stopRendering = function () {
+        this._explicitlyStoppedRendering = true;
         if (this.loaded && this.frameRequestId) {
             if (this.runtime.cancelAnimationFrame) {
                 this.runtime.cancelAnimationFrame(this.frameRequestId);
@@ -6107,6 +6397,7 @@ var Rive = /** @class */ (function () {
      * renderer is already active, then this will have zero effect.
      */
     Rive.prototype.startRendering = function () {
+        this._explicitlyStoppedRendering = false;
         this.drawFrame();
     };
     Rive.prototype.scheduleRendering = function () {
@@ -6119,6 +6410,31 @@ var Rive = /** @class */ (function () {
             }
         }
     };
+    /**
+     * Called when document.visibilitychange fires (tab change, window minimize, etc.).
+     * Cancels the rAF loop on hide and resets the time reference so that no accumulated time is
+     * applied to state machines when the tab becomes visible again. This prevents state machine
+     * advances with large time deltas when rAF starts up again.
+     */
+    Rive.prototype._onPageVisibilityChange = function () {
+        var _a, _b;
+        if (document.hidden) {
+            if (this.frameRequestId !== null) {
+                if ((_a = this.runtime) === null || _a === void 0 ? void 0 : _a.cancelAnimationFrame) {
+                    this.runtime.cancelAnimationFrame(this.frameRequestId);
+                }
+                else {
+                    cancelAnimationFrame(this.frameRequestId);
+                }
+                this.frameRequestId = null;
+            }
+            // Reset so the first resumed frame starts with elapsedTime === 0.
+            this.lastRenderTime = 0;
+        }
+        else if (((_b = this.animator) === null || _b === void 0 ? void 0 : _b.isPlaying) && !this._explicitlyStoppedRendering) {
+            this.scheduleRendering();
+        }
+    };
     /**
      * Enables frames-per-second (FPS) reporting for the runtime
      * If no callback is provided, Rive will append a fixed-position div at the top-right corner of
@@ -6356,6 +6672,14 @@ var Rive = /** @class */ (function () {
         var _a, _b;
         return (_b = (_a = this.riveFile) === null || _a === void 0 ? void 0 : _a.getDefaultBindableArtboard()) !== null && _b !== void 0 ? _b : null;
     };
+    /**
+     * Clear focus applicable to active state machines with focus nodes. Useful if users want to
+     * reset focus state and behavior within the Rive graphic at any point (i.e. blurring off the canvas)
+     */
+    Rive.prototype.clearFocus = function () {
+        var playingStateMachines = this.animator.stateMachines.filter(function (sm) { return sm.playing && sm.hasFocusNodes; });
+        playingStateMachines.forEach(function (sm) { return sm.clearFocus(); });
+    };
     // Error message for missing source or buffer
     Rive.missingErrorMessage = "Rive source file or data buffer required";
     // Error message for removed rive file