@rive-app/canvas-lite 2.40.0 → 2.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/rive.js CHANGED
@@ -449,7 +449,7 @@ Hc=await (async function(){function b(c){c=Hc=c.exports;gb=c.V;Ec=c.W;fb=c.X;Fc=
449
449
  /* 5 */
450
450
  /***/ ((module) => {
451
451
 
452
- module.exports = /*#__PURE__*/JSON.parse('{"name":"@rive-app/canvas-lite","version":"2.40.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","semantics"],"typings":"rive.d.ts","dependencies":{},"browser":{"fs":false,"path":false}}');
452
+ module.exports = /*#__PURE__*/JSON.parse('{"name":"@rive-app/canvas-lite","version":"2.41.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","semantics"],"typings":"rive.d.ts","dependencies":{},"browser":{"fs":false,"path":false}}');
453
453
 
454
454
  /***/ }),
455
455
  /* 6 */
@@ -2605,21 +2605,21 @@ __webpack_require__.r(__webpack_exports__);
2605
2605
  /* harmony export */ KeyboardInteractions: () => (/* binding */ KeyboardInteractions)
2606
2606
  /* harmony export */ });
2607
2607
  /**
2608
- * Tracks the relationship between the canvas's DOM focus and Rive's internal focus for the
2609
- * current focus session.
2608
+ * Tracks the relationship between DOM focus inside this Rive focus domain (canvas or semantic overlay)
2609
+ * and Rive's internal focus for the current focus session.
2610
2610
  *
2611
- * NotFocused — the canvas is not the active DOM element, or Rive entered and then released focus
2612
- * internally this session. Either way the next Tab should move on to the next page
2613
- * element, so Tab events are ignored.
2614
- * EntryPending — the canvas has DOM focus but Rive holds no active focus node yet, and the next Tab should enter
2615
- * the focus tree. This is the resting state for pointer-driven focus (a click on the
2616
- * canvas), or an edge case for keyboard focus where initial focus action did not land on a focus node.
2617
- * RiveFocused — a Rive node currently holds focus. Tab/Shift+Tab are routed to the Rive focus
2618
- * manager and trapped inside the canvas until Rive notifies focus has ended.
2611
+ * NotFocused — DOM focus left the domain, Rive released focus internally, or Tab walked
2612
+ * off the end of the tree. Keyboard input isn't ours, so Tab is ignored and
2613
+ * reaches the next page element.
2614
+ * EntryPending — DOM focus is inside the domain but Rive holds no node yet, so the next Tab
2615
+ * enters the focus tree. Set by pointer focus on the canvas, by assistive technology (AT) focus landing
2616
+ * in the overlay, and by keyboard focus whose entry attempt found no eligible node.
2617
+ * RiveFocused — a Rive node holds focus. Tab/Shift+Tab route to the Rive focus manager and stay
2618
+ * inside the domain until either Rive reports focus ended (pollFocusState) or
2619
+ * focusNext()/focusPrevious() returns false at the edge of the tree.
2619
2620
  *
2620
- * When keyboard focus lands on the canvas, onCanvasFocus reads the direction focus came from and
2621
- * moves into the focus tree immediately, going straight to RiveFocused. EntryPending is only set via pointer focus (or keyboard focus
2622
- * where focusNext()/focusPrevious() return false but respects tabindex).
2621
+ * Keyboard focus on the canvas enters the tree immediately: onCanvasFocus infers direction from
2622
+ * where focus came from and goes straight to RiveFocused when a node accepts.
2623
2623
  */
2624
2624
  var FocusSessionState;
2625
2625
  (function (FocusSessionState) {
@@ -2628,7 +2628,9 @@ var FocusSessionState;
2628
2628
  FocusSessionState["RiveFocused"] = "riveFocused";
2629
2629
  })(FocusSessionState || (FocusSessionState = {}));
2630
2630
  /**
2631
- * Manages keyboard and DOM focus interactions for a Rive canvas.
2631
+ * Manages keyboard and DOM focus interactions for Rive's focus domain (<canvas> or semantic overlay).
2632
+ * Because keyboard events can apply on either part of the domain, we need to track what events we should
2633
+ * handle/intercept, and when to release focus back to the page outside of the domain.
2632
2634
  *
2633
2635
  * Tracks the canvas focus session state (focusSessionState) and routes
2634
2636
  * Tab/Shift+Tab to the Rive state machine's focus manager. Exposes shared
@@ -2674,17 +2676,45 @@ var KeyboardInteractions = /** @class */ (function () {
2674
2676
  _this.focusSessionState = FocusSessionState.RiveFocused;
2675
2677
  }
2676
2678
  };
2677
- this.onCanvasBlur = function (_event) {
2679
+ /**
2680
+ * Marks internal state that the canvas has lost DOM focus. Do not actually clear
2681
+ * Rive focus though if:
2682
+ * 1. DOM focus is still within Rive domain (i.e., semantic overlay)
2683
+ * 2. Document just lost focus (i.e. tab switching)
2684
+ *
2685
+ * When we're not in either of those buckets, it's safe to call `clearFocus()` on the SMI.
2686
+ */
2687
+ this.onCanvasBlur = function (event) {
2678
2688
  _this.focusSessionState = FocusSessionState.NotFocused;
2679
2689
  _this.canvasHasFocus = false;
2690
+ var movedWithinFocusDomain = _this.isInFocusDomain(event.relatedTarget);
2691
+ var documentLostFocus = event.relatedTarget === null && !document.hasFocus();
2692
+ if (movedWithinFocusDomain || documentLostFocus)
2693
+ return;
2694
+ _this.mainSm.clearFocus();
2680
2695
  };
2696
+ /**
2697
+ * Assistive technology (AT) focus landing inside the overlay is DOM focus inside the Rive focus domain, so open a
2698
+ * session even when no Rive node holds focus yet. shouldRiveHandleKeyEvent treats NotFocused
2699
+ * as authoritative, so without this the overlay's Tab keydowns reach onKeyDown and get dropped
2700
+ * at that gate — the browser would move focus out of Rive instead of to the next focus node.
2701
+ */
2681
2702
  this.onOverlayFocusIn = function (event) {
2682
- if (_this.isInOverlay(event.target)) {
2683
- _this.focusDomainReleased = false;
2684
- }
2703
+ if (!_this.isInOverlay(event.target))
2704
+ return;
2705
+ _this.focusDomainReleased = false;
2706
+ if (!_this.hasFocusNodes)
2707
+ return;
2708
+ if (_this.focusSessionState !== FocusSessionState.NotFocused)
2709
+ return;
2710
+ _this.focusSessionState = _this.mainSm.focusState().hasFocus
2711
+ ? FocusSessionState.RiveFocused
2712
+ : FocusSessionState.EntryPending;
2685
2713
  };
2686
- this.onFocusDomainHostFocusIn = function (_event) {
2714
+ /** Overlay listeners attach lazily, so the first focusin only ever lands here. */
2715
+ this.onFocusDomainHostFocusIn = function (event) {
2687
2716
  _this.syncOverlayListener();
2717
+ _this.onOverlayFocusIn(event);
2688
2718
  };
2689
2719
  this.onKeyDown = function (event) {
2690
2720
  _this.syncOverlayListener();
@@ -2697,7 +2727,7 @@ var KeyboardInteractions = /** @class */ (function () {
2697
2727
  var forward = !event.shiftKey;
2698
2728
  var focusMoved = forward ? _this.mainSm.focusNext() : _this.mainSm.focusPrevious();
2699
2729
  if (focusMoved) {
2700
- // A Rive node accepted focus — keep trapping Tab inside the canvas.
2730
+ // A Rive node accepted focus — keep trapping Tab inside Rive.
2701
2731
  _this.focusSessionState = FocusSessionState.RiveFocused;
2702
2732
  event.preventDefault();
2703
2733
  }
@@ -2733,27 +2763,34 @@ var KeyboardInteractions = /** @class */ (function () {
2733
2763
  /**
2734
2764
  * Called by pollFocusState on the Rive instance when it observes hasFocus=true. Rive acquired
2735
2765
  * focus internally (e.g. via a listener action or state transition) without a DOM focus event,
2736
- * so mark the session RiveFocused.
2766
+ * so mark the session RiveFocused. This cannot resurrect a session that a DOM blur ended,
2767
+ * because onCanvasBlur clears Rive's focus alongside it.
2737
2768
  */
2738
2769
  KeyboardInteractions.prototype.notifyRiveFocused = function () {
2739
2770
  this.focusSessionState = FocusSessionState.RiveFocused;
2740
2771
  };
2741
2772
  /**
2742
- * Whether Rive should handle this keydown — i.e. it currently owns keyboard input.
2743
- * True when focus is anywhere in the Rive focus domain (the canvas itself or the
2744
- * accessibility overlay), OR a focus session is active and the key landed on the
2745
- * canvas.
2773
+ * Determine if Rive should handle keyboard input. If session state is `NotFocused` - no.
2774
+ * DOM focus stays parked on the canvas after Rive releases focus internally, and that Tab
2775
+ * has to reach the page rather than re-enter the tree.
2776
+ *
2777
+ * Otherwise, the event still has to belong to Rive:
2778
+ * 1. If the current DOM focus is in Rive domain (canvas or semantic overlay)
2779
+ * 2. If the target for the key input is for the semantic overlay, or the canvas
2746
2780
  */
2747
2781
  KeyboardInteractions.prototype.shouldRiveHandleKeyEvent = function (event) {
2782
+ if (this.focusSessionState === FocusSessionState.NotFocused)
2783
+ return false;
2748
2784
  var inFocusDomain = this.isInFocusDomain(document.activeElement) ||
2749
2785
  this.isInOverlay(event.target);
2750
- if (inFocusDomain)
2751
- return true;
2752
- var sessionActive = this.focusSessionState !== FocusSessionState.NotFocused;
2753
2786
  var eventOnCanvas = event.target === this.canvas;
2754
- return sessionActive && (this.canvasHasFocus || eventOnCanvas);
2787
+ return inFocusDomain || this.canvasHasFocus || eventOnCanvas;
2755
2788
  };
2756
- /** Rive focus domain = the canvas itself OR the accessibility overlay. */
2789
+ /**
2790
+ * The Rive focus domain: the DOM that counts as "inside" Rive for focus purposes — today the
2791
+ * canvas itself OR the accessibility overlay subtree. Anything added later belongs here, so
2792
+ * session bookkeeping and keydown routing pick it up for free.
2793
+ */
2757
2794
  KeyboardInteractions.prototype.isInFocusDomain = function (target) {
2758
2795
  if (target === this.canvas)
2759
2796
  return true;
@@ -3537,6 +3574,12 @@ var Layout = /** @class */ (function () {
3537
3574
 
3538
3575
  // #endregion
3539
3576
  // #region state machines
3577
+ /**
3578
+ * @deprecated State machine inputs are deprecated and will be removed in a
3579
+ * future major version: please use data binding properties instead. See
3580
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
3581
+ * for how to migrate.
3582
+ */
3540
3583
  var StateMachineInputType;
3541
3584
  (function (StateMachineInputType) {
3542
3585
  StateMachineInputType[StateMachineInputType["Number"] = 56] = "Number";
@@ -3545,6 +3588,10 @@ var StateMachineInputType;
3545
3588
  })(StateMachineInputType || (StateMachineInputType = {}));
3546
3589
  /**
3547
3590
  * An input for a state machine
3591
+ * @deprecated State machine inputs are deprecated and will be removed in a
3592
+ * future major version: please use data binding properties instead. See
3593
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
3594
+ * for how to migrate.
3548
3595
  */
3549
3596
  var StateMachineInput = /** @class */ (function () {
3550
3597
  function StateMachineInput(type, runtimeInput) {
@@ -3594,6 +3641,11 @@ var StateMachineInput = /** @class */ (function () {
3594
3641
  return StateMachineInput;
3595
3642
  }());
3596
3643
 
3644
+ /**
3645
+ * @deprecated Rive Events are deprecated and will be removed in a future major
3646
+ * version: please use data binding instead. See
3647
+ * {@link https://rive.app/docs/runtimes/web/rive-events} for how to migrate.
3648
+ */
3597
3649
  var RiveEventType;
3598
3650
  (function (RiveEventType) {
3599
3651
  RiveEventType[RiveEventType["General"] = 128] = "General";
@@ -4136,6 +4188,12 @@ var Animator = /** @class */ (function () {
4136
4188
  var instancedName;
4137
4189
  if (this.animations.length === 0 && this.stateMachines.length === 0) {
4138
4190
  if (this.artboard.animationCount() > 0) {
4191
+ // Warn only when the v3 default would actually change what plays
4192
+ if (this.artboard.stateMachineCount() > 0) {
4193
+ warnOnce("No `stateMachine` was specified, so the artboard's first linear animation is playing by default. " +
4194
+ "In the next major version, the artboard's state machine will be played by default instead when one exists. " +
4195
+ "Pass the `stateMachine` parameter to adopt that behavior now.");
4196
+ }
4139
4197
  // Add the first animation
4140
4198
  this.add([(instancedName = this.artboard.animationByIndex(0).name)], playing, fireEvent);
4141
4199
  }
@@ -4214,15 +4272,84 @@ var EventType;
4214
4272
  EventType["Play"] = "play";
4215
4273
  EventType["Pause"] = "pause";
4216
4274
  EventType["Stop"] = "stop";
4275
+ /**
4276
+ * @deprecated Loop events are deprecated and will be removed in a future
4277
+ * major version: they are only reported for linear animation playback, which
4278
+ * is deprecated. Use a state machine to control playback and data binding to
4279
+ * react to changes instead. See
4280
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide} for how
4281
+ * to migrate.
4282
+ */
4217
4283
  EventType["Loop"] = "loop";
4218
4284
  EventType["Draw"] = "draw";
4219
4285
  EventType["Advance"] = "advance";
4286
+ /**
4287
+ * @deprecated State change events are deprecated and will be removed in a
4288
+ * future major version. Use data binding (view model property observers) or
4289
+ * state machine actions to react to changes from your graphic instead. See
4290
+ * {@link https://rive.app/docs/editor/state-machine/states#actions} for more details.
4291
+ */
4220
4292
  EventType["StateChange"] = "statechange";
4293
+ /**
4294
+ * @deprecated Rive Events are deprecated and will be removed in a future
4295
+ * major version: please use data binding instead. See
4296
+ * {@link https://rive.app/docs/runtimes/web/rive-events} for how to migrate.
4297
+ */
4221
4298
  EventType["RiveEvent"] = "riveevent";
4222
4299
  EventType["AudioStatusChange"] = "audiostatuschange";
4223
4300
  })(EventType || (EventType = {}));
4301
+ var riveEventsDeprecationWarning = "Rive Events are deprecated and will be removed in a future major version: " +
4302
+ "please use data binding instead. See " +
4303
+ "https://rive.app/docs/runtimes/web/rive-events for how to migrate.";
4304
+ var stateMachineInputsDeprecationWarning = "State machine inputs are deprecated and will be removed in a future major version: " +
4305
+ "please use data binding properties instead. See " +
4306
+ "https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs for how to migrate.";
4307
+ var textRunsDeprecationWarning = "Text run APIs are deprecated and will be removed in a future major version: " +
4308
+ "please use data binding instead. See " +
4309
+ "https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime for how to migrate.";
4310
+ var loopEventsDeprecationWarning = "Loop events are deprecated and will be removed in a future major version: " +
4311
+ "they are only reported for linear animation playback, which is deprecated. " +
4312
+ "Use a state machine to control playback and data binding to react to changes instead. See " +
4313
+ "https://rive.app/docs/editor/data-binding/migration-guide for how to migrate.";
4314
+ var stateChangeEventsDeprecationWarning = "State change events are deprecated and will be removed in a future major version: " +
4315
+ "use data binding (view model property observers) or state machine actions to react to " +
4316
+ "changes from your graphic instead. See " +
4317
+ "https://rive.app/docs/editor/state-machine/states#actions for how to migrate.";
4318
+ // Deprecation warnings already emitted; each is logged at most once per page
4319
+ // session to avoid flooding the console when many instances are created.
4320
+ var emittedWarnings = new Set();
4321
+ var warnOnce = function (message) {
4322
+ if (!emittedWarnings.has(message)) {
4323
+ emittedWarnings.add(message);
4324
+ console.warn("[Rive] ".concat(message));
4325
+ }
4326
+ };
4327
+ /**
4328
+ * Warns that a playback-control method received an array of names; the next
4329
+ * major version restricts these parameters to a single string, since playing
4330
+ * multiple animations or state machines at once will not be supported.
4331
+ */
4332
+ var warnIfNamesArray = function (names, methodName) {
4333
+ if (Array.isArray(names)) {
4334
+ warnOnce("Passing an array of names to `".concat(methodName, "()` is deprecated: in the next major version this parameter will be a single string, and playing multiple animations or state machines at once will not be supported."));
4335
+ }
4336
+ };
4337
+ /**
4338
+ * Warns that a playback-control method received linear animation names;
4339
+ * name-based control remains supported for state machines only, so
4340
+ * user-specified linear animation names are going away in a future major
4341
+ * version.
4342
+ */
4343
+ var warnDeprecatedAnimationNames = function (methodName) {
4344
+ warnOnce("Passing linear animation names to `".concat(methodName, "()` is deprecated and will be removed in a future major version: ") +
4345
+ "Pass a single state machine name to control playback instead.");
4346
+ };
4224
4347
  /**
4225
4348
  * Looping types: one-shot, loop, and ping-pong
4349
+ * @deprecated Loop events are deprecated and will be removed in a future major
4350
+ * version: they are only reported for linear animation playback, which is
4351
+ * deprecated. Use a state machine to control playback and data binding to
4352
+ * react to changes instead.
4226
4353
  */
4227
4354
  var LoopType;
4228
4355
  (function (LoopType) {
@@ -4536,6 +4663,31 @@ var observers = new ObjectObservers();
4536
4663
  // #endregion
4537
4664
  // #region Rive
4538
4665
  var nextRiveInstanceId = 0;
4666
+ /**
4667
+ * Resolves which animation/state machine names playback should start with.
4668
+ * The `stateMachine` parameter takes priority; the deprecated plural
4669
+ * `animations`/`stateMachines` parameters apply only when it
4670
+ * is not provided.
4671
+ */
4672
+ var resolveStartingPlayback = function (_a) {
4673
+ var stateMachine = _a.stateMachine, animations = _a.animations, stateMachines = _a.stateMachines;
4674
+ if (animations !== undefined) {
4675
+ warnOnce("The `animations` parameter is deprecated and will be removed in a future major version: please use the `stateMachine` parameter to play a state machine instead.");
4676
+ }
4677
+ if (stateMachines !== undefined) {
4678
+ warnOnce("The `stateMachines` parameter is deprecated: please use `stateMachine` with a single state machine name instead.");
4679
+ }
4680
+ if (stateMachine) {
4681
+ return {
4682
+ startingAnimationNames: [],
4683
+ startingStateMachineNames: [stateMachine],
4684
+ };
4685
+ }
4686
+ return {
4687
+ startingAnimationNames: mapToStringArray(animations),
4688
+ startingStateMachineNames: mapToStringArray(stateMachines),
4689
+ };
4690
+ };
4539
4691
  var RiveFile = /** @class */ (function () {
4540
4692
  function RiveFile(params) {
4541
4693
  // Allow the runtime to automatically load assets hosted in Rive's runtime.
@@ -4957,6 +5109,10 @@ var Rive = /** @class */ (function () {
4957
5109
  this.layout = (_a = params.layout) !== null && _a !== void 0 ? _a : new Layout();
4958
5110
  this.shouldDisableRiveListeners = !!params.shouldDisableRiveListeners;
4959
5111
  this.isTouchScrollEnabled = !!params.isTouchScrollEnabled;
5112
+ if (params.automaticallyHandleEvents) {
5113
+ warnOnce("The `automaticallyHandleEvents` parameter is deprecated. " +
5114
+ riveEventsDeprecationWarning);
5115
+ }
4960
5116
  this.automaticallyHandleEvents = !!params.automaticallyHandleEvents;
4961
5117
  this.dispatchPointerExit =
4962
5118
  params.dispatchPointerExit === false
@@ -5021,6 +5177,7 @@ var Rive = /** @class */ (function () {
5021
5177
  riveFile: this.riveFile,
5022
5178
  autoplay: params.autoplay,
5023
5179
  autoBind: params.autoBind,
5180
+ stateMachine: params.stateMachine,
5024
5181
  animations: params.animations,
5025
5182
  stateMachines: params.stateMachines,
5026
5183
  artboard: params.artboard,
@@ -5087,7 +5244,7 @@ var Rive = /** @class */ (function () {
5087
5244
  // Initializes the Rive object either from constructor or load()
5088
5245
  Rive.prototype.init = function (_a) {
5089
5246
  var _this = this;
5090
- 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, semanticsMode = _a.semanticsMode, semanticsOptions = _a.semanticsOptions;
5247
+ var src = _a.src, buffer = _a.buffer, riveFile = _a.riveFile, stateMachine = _a.stateMachine, 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, semanticsMode = _a.semanticsMode, semanticsOptions = _a.semanticsOptions;
5091
5248
  if (this.destroyed) {
5092
5249
  return;
5093
5250
  }
@@ -5101,10 +5258,12 @@ var Rive = /** @class */ (function () {
5101
5258
  if (!this.src && !this.buffer && !this.riveFile) {
5102
5259
  throw new RiveError(Rive.missingErrorMessage);
5103
5260
  }
5104
- // List of animations that should be initialized.
5105
- var startingAnimationNames = mapToStringArray(animations);
5106
- // List of state machines that should be initialized
5107
- var startingStateMachineNames = mapToStringArray(stateMachines);
5261
+ // Names of the animations and state machines that should be initialized
5262
+ var _e = resolveStartingPlayback({
5263
+ stateMachine: stateMachine,
5264
+ animations: animations,
5265
+ stateMachines: stateMachines,
5266
+ }), startingAnimationNames = _e.startingAnimationNames, startingStateMachineNames = _e.startingStateMachineNames;
5108
5267
  // Ensure loaded is marked as false if loading new file
5109
5268
  this.loaded = false;
5110
5269
  this.readyForPlaying = false;
@@ -5460,8 +5619,9 @@ var Rive = /** @class */ (function () {
5460
5619
  // Rive has an active focus node. Mark the session RiveFocused so Tab stays
5461
5620
  // trapped and a later internal release (hasFocus true → false) is detected.
5462
5621
  this._keyboardInteractions.notifyRiveFocused();
5463
- // Only steal DOM focus on the false→true transition. If hasFocus stays
5464
- // true across frames and the user clicks away, do not re-focus the canvas again.
5622
+ // Only steal DOM focus on the false→true transition. Rive can hold focus across
5623
+ // frames while DOM focus sits elsewhere — a window switch preserves runtime focus
5624
+ // by design — and that must not re-focus the canvas again.
5465
5625
  if (!this._prevHasFocus) {
5466
5626
  // Steal DOM focus to the canvas only when focus isn't already held
5467
5627
  // somewhere inside this instance's focus scope. When the accessibility
@@ -5482,8 +5642,9 @@ var Rive = /** @class */ (function () {
5482
5642
  this._prevHasFocus = false;
5483
5643
  // hasFocus is false — only act when Rive previously held focus and released it internally
5484
5644
  // (state change clears focus). Release the DOM Tab trap so the next Tab moves to the next
5485
- // page element. EntryPending and NotFocused cases are intentional no-ops — EntryPending in
5486
- // particular must stay in its state (a click awaiting its first Tab) rather than be reset here.
5645
+ // page element. A DOM blur reaches here too now that onCanvasBlur clears Rive focus, but it
5646
+ // has already set NotFocused, so this is a no-op. EntryPending and NotFocused are likewise
5647
+ // intentional no-ops — EntryPending must stay put (a click awaiting its first Tab).
5487
5648
  if (this._keyboardInteractions.focusSessionState === _utils__WEBPACK_IMPORTED_MODULE_3__.FocusSessionState.RiveFocused) {
5488
5649
  this._keyboardInteractions.setFocusSessionState(_utils__WEBPACK_IMPORTED_MODULE_3__.FocusSessionState.NotFocused);
5489
5650
  }
@@ -5819,6 +5980,7 @@ var Rive = /** @class */ (function () {
5819
5980
  * might happen.
5820
5981
  */
5821
5982
  Rive.prototype.cleanupInstances = function () {
5983
+ var _a;
5822
5984
  if (this.eventCleanup !== null) {
5823
5985
  this.eventCleanup();
5824
5986
  }
@@ -5826,8 +5988,9 @@ var Rive = /** @class */ (function () {
5826
5988
  // Tear down semantics before deleting state machines — the overlay's action
5827
5989
  // closures point at instances that stop() is about to free.
5828
5990
  this.cleanupSemantics();
5829
- // Delete all animation and state machine instances
5830
- this.stop();
5991
+ // Delete all animation and state machine instances synchronously via the
5992
+ // animator
5993
+ (_a = this.animator) === null || _a === void 0 ? void 0 : _a.stop();
5831
5994
  if (this.artboard) {
5832
5995
  this.artboard.delete();
5833
5996
  this.artboard = null;
@@ -5860,29 +6023,58 @@ var Rive = /** @class */ (function () {
5860
6023
  * Returns a string from a given text run node name, or undefined if the text run
5861
6024
  * cannot be queried.
5862
6025
  *
6026
+ * @deprecated Text run APIs are deprecated: use data binding instead. See
6027
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
6028
+ * for how to migrate.
5863
6029
  * @param textRunName - Name of the text run node associated with a text object
5864
6030
  * @returns - String value of the text run node or undefined
5865
6031
  */
5866
6032
  Rive.prototype.getTextRunValue = function (textRunName) {
6033
+ warnOnce(textRunsDeprecationWarning);
5867
6034
  var textRun = this.retrieveTextRun(textRunName);
5868
6035
  return textRun ? textRun.text : undefined;
5869
6036
  };
5870
6037
  /**
5871
6038
  * Sets a text value for a given text run node name if possible
5872
6039
  *
6040
+ * @deprecated Text run APIs are deprecated: use data binding instead. See
6041
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
6042
+ * for how to migrate.
5873
6043
  * @param textRunName - Name of the text run node associated with a text object
5874
6044
  * @param textRunValue - String value to set on the text run node
5875
6045
  */
5876
6046
  Rive.prototype.setTextRunValue = function (textRunName, textRunValue) {
6047
+ warnOnce(textRunsDeprecationWarning);
5877
6048
  var textRun = this.retrieveTextRun(textRunName);
5878
6049
  if (textRun) {
5879
6050
  textRun.text = textRunValue;
5880
6051
  }
5881
6052
  };
5882
- // Plays specified animations; if none specified, it unpauses everything.
6053
+ /**
6054
+ * Warns when playback-control names match linear animations in the
6055
+ * Animator's instanced context; state machine playback remain supported.
6056
+ *
6057
+ * Remove for v3 release
6058
+ */
6059
+ Rive.prototype.warnIfLinearAnimationNames = function (names, methodName) {
6060
+ if (this.animator &&
6061
+ this.animator.animations.some(function (a) { return names.includes(a.name); })) {
6062
+ warnDeprecatedAnimationNames(methodName);
6063
+ }
6064
+ };
6065
+ /**
6066
+ * Plays specified animations or state machines; if none specified, it
6067
+ * unpauses everything.
6068
+ * @param animationNames Animation or state machine name(s) to play.
6069
+ *
6070
+ * Deprecated usage: passing linear animation names (control playback with a
6071
+ * state machine instead) and passing an array of names (this parameter
6072
+ * becomes a single string in the next major version).
6073
+ */
5883
6074
  Rive.prototype.play = function (animationNames, autoplay) {
5884
6075
  var _this = this;
5885
- animationNames = mapToStringArray(animationNames);
6076
+ warnIfNamesArray(animationNames, "play");
6077
+ var names = mapToStringArray(animationNames);
5886
6078
  // If the file's not loaded, queue up the play
5887
6079
  if (!this.readyForPlaying) {
5888
6080
  this.taskQueue.add({
@@ -5890,7 +6082,8 @@ var Rive = /** @class */ (function () {
5890
6082
  });
5891
6083
  return;
5892
6084
  }
5893
- this.animator.play(animationNames);
6085
+ this.animator.play(names);
6086
+ this.warnIfLinearAnimationNames(names, "play");
5894
6087
  this.syncSemanticsOnStateMachines();
5895
6088
  if (this.eventCleanup) {
5896
6089
  this.eventCleanup();
@@ -5899,10 +6092,19 @@ var Rive = /** @class */ (function () {
5899
6092
  this.setupRiveListeners();
5900
6093
  this.startRendering();
5901
6094
  };
5902
- // Pauses specified animations; if none specified, pauses all.
6095
+ /**
6096
+ * Pauses specified animations or state machines; if none specified, pauses
6097
+ * all.
6098
+ * @param animationNames Animation or state machine name(s) to pause.
6099
+ *
6100
+ * Deprecated usage: passing linear animation names (control playback with a
6101
+ * state machine instead) and passing an array of names (this parameter
6102
+ * becomes a single string in the next major version).
6103
+ */
5903
6104
  Rive.prototype.pause = function (animationNames) {
5904
6105
  var _this = this;
5905
- animationNames = mapToStringArray(animationNames);
6106
+ warnIfNamesArray(animationNames, "pause");
6107
+ var names = mapToStringArray(animationNames);
5906
6108
  // If the file's not loaded, early out, nothing to pause
5907
6109
  if (!this.readyForPlaying) {
5908
6110
  this.taskQueue.add({
@@ -5914,11 +6116,20 @@ var Rive = /** @class */ (function () {
5914
6116
  this.eventCleanup();
5915
6117
  }
5916
6118
  this.cleanupKeyboardInteractions();
5917
- this.animator.pause(animationNames);
6119
+ this.animator.pause(names);
6120
+ this.warnIfLinearAnimationNames(names, "pause");
5918
6121
  };
6122
+ /**
6123
+ * Scrubs specified animations to the given time; if none specified, scrubs
6124
+ * all of them.
6125
+ * @deprecated `scrub()` will be removed in a future major version: use a
6126
+ * state machine to control playback instead
6127
+ */
5919
6128
  Rive.prototype.scrub = function (animationNames, value) {
5920
6129
  var _this = this;
5921
- animationNames = mapToStringArray(animationNames);
6130
+ warnOnce("`scrub()` is deprecated and will be removed in a future major version: " +
6131
+ "use a state machine to control playback instead.");
6132
+ var names = mapToStringArray(animationNames);
5922
6133
  // If the file's not loaded, early out, nothing to pause
5923
6134
  if (!this.readyForPlaying) {
5924
6135
  this.taskQueue.add({
@@ -5928,13 +6139,22 @@ var Rive = /** @class */ (function () {
5928
6139
  }
5929
6140
  // Scrub the animation time; we draw a single frame here so that if
5930
6141
  // nothing's currently playing, the scrubbed animation is still rendered/
5931
- this.animator.scrub(animationNames, value || 0);
6142
+ this.animator.scrub(names, value || 0);
5932
6143
  this.drawFrame();
5933
6144
  };
5934
- // Stops specified animations; if none specifies, stops them all.
6145
+ /**
6146
+ * Stops specified animations or state machines; if none specified, stops
6147
+ * them all.
6148
+ * @param animationNames Animation or state machine name(s) to stop.
6149
+ *
6150
+ * Deprecated usage: passing linear animation names (control playback with a
6151
+ * state machine instead) and passing an array of names (this parameter
6152
+ * becomes a single string in the next major version).
6153
+ */
5935
6154
  Rive.prototype.stop = function (animationNames) {
5936
6155
  var _this = this;
5937
- animationNames = mapToStringArray(animationNames);
6156
+ warnIfNamesArray(animationNames, "stop");
6157
+ var names = mapToStringArray(animationNames);
5938
6158
  // If the file's not loaded, early out, nothing to pause
5939
6159
  if (!this.readyForPlaying) {
5940
6160
  this.taskQueue.add({
@@ -5942,9 +6162,10 @@ var Rive = /** @class */ (function () {
5942
6162
  });
5943
6163
  return;
5944
6164
  }
6165
+ this.warnIfLinearAnimationNames(names, "stop");
5945
6166
  // If there is no artboard, this.animator will be undefined
5946
6167
  if (this.animator) {
5947
- this.animator.stop(animationNames);
6168
+ this.animator.stop(names);
5948
6169
  }
5949
6170
  if (this.eventCleanup) {
5950
6171
  this.eventCleanup();
@@ -5955,8 +6176,7 @@ var Rive = /** @class */ (function () {
5955
6176
  /**
5956
6177
  * Resets the animation
5957
6178
  * @param artboard the name of the artboard, or default if none given
5958
- * @param animations the names of animations for playback
5959
- * @param stateMachines the names of state machines for playback
6179
+ * @param stateMachine the name of the state machine for playback
5960
6180
  * @param autoplay whether to autoplay when reset, defaults to false
5961
6181
  *
5962
6182
  */
@@ -5964,15 +6184,22 @@ var Rive = /** @class */ (function () {
5964
6184
  var _a, _b;
5965
6185
  // Get the current artboard, animations, state machines, and playback states
5966
6186
  var artBoardName = params === null || params === void 0 ? void 0 : params.artboard;
5967
- var animationNames = mapToStringArray(params === null || params === void 0 ? void 0 : params.animations);
5968
- var stateMachineNames = mapToStringArray(params === null || params === void 0 ? void 0 : params.stateMachines);
6187
+ var _c = resolveStartingPlayback({
6188
+ stateMachine: params === null || params === void 0 ? void 0 : params.stateMachine,
6189
+ animations: params === null || params === void 0 ? void 0 : params.animations,
6190
+ stateMachines: params === null || params === void 0 ? void 0 : params.stateMachines,
6191
+ }), animationNames = _c.startingAnimationNames, stateMachineNames = _c.startingStateMachineNames;
5969
6192
  var autoplay = (_a = params === null || params === void 0 ? void 0 : params.autoplay) !== null && _a !== void 0 ? _a : false;
5970
6193
  var autoBind = (_b = params === null || params === void 0 ? void 0 : params.autoBind) !== null && _b !== void 0 ? _b : false;
5971
6194
  // Stop everything and clean up
5972
6195
  this.cleanupInstances();
5973
6196
  // Reinitialize an artboard instance with the state
5974
6197
  this.initArtboard(artBoardName, animationNames, stateMachineNames, autoplay, autoBind);
5975
- this.taskQueue.process();
6198
+ // Only drain the task queue once playback commands can execute; tasks
6199
+ // queued before then re-add themselves in a loop.
6200
+ if (this.readyForPlaying) {
6201
+ this.taskQueue.process();
6202
+ }
5976
6203
  };
5977
6204
  // Loads a new Rive file, keeping listeners in place
5978
6205
  Rive.prototype.load = function (params) {
@@ -6127,11 +6354,18 @@ var Rive = /** @class */ (function () {
6127
6354
  });
6128
6355
  /**
6129
6356
  * Returns the inputs for the specified instanced state machine, or an empty
6130
- * list if the name is invalid or the state machine is not instanced
6357
+ * list if the name is invalid or the state machine is not instanced. Returns
6358
+ * undefined if the file is not loaded yet.
6359
+ *
6360
+ * @deprecated State machine inputs are deprecated: use data binding
6361
+ * properties instead. See
6362
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
6363
+ * for how to migrate.
6131
6364
  * @param name the state machine name
6132
- * @returns the inputs for the named state machine
6365
+ * @returns the inputs for the named state machine or undefined
6133
6366
  */
6134
6367
  Rive.prototype.stateMachineInputs = function (name) {
6368
+ warnOnce(stateMachineInputsDeprecationWarning);
6135
6369
  // If the file's not loaded, early out, nothing to pause
6136
6370
  if (!this.loaded) {
6137
6371
  return;
@@ -6158,11 +6392,16 @@ var Rive = /** @class */ (function () {
6158
6392
  };
6159
6393
  /**
6160
6394
  * Set the boolean input with the provided name at the given path with value
6395
+ * @deprecated State machine inputs are deprecated: use data binding
6396
+ * properties instead. See
6397
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
6398
+ * for how to migrate.
6161
6399
  * @param input the state machine input name
6162
6400
  * @param value the value to set the input to
6163
6401
  * @param path the path the input is located at an artboard level
6164
6402
  */
6165
6403
  Rive.prototype.setBooleanStateAtPath = function (inputName, value, path) {
6404
+ warnOnce(stateMachineInputsDeprecationWarning);
6166
6405
  var input = this.retrieveInputAtPath(inputName, path);
6167
6406
  if (!input)
6168
6407
  return;
@@ -6175,11 +6414,16 @@ var Rive = /** @class */ (function () {
6175
6414
  };
6176
6415
  /**
6177
6416
  * Set the number input with the provided name at the given path with value
6417
+ * @deprecated State machine inputs are deprecated: use data binding
6418
+ * properties instead. See
6419
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
6420
+ * for how to migrate.
6178
6421
  * @param input the state machine input name
6179
6422
  * @param value the value to set the input to
6180
6423
  * @param path the path the input is located at an artboard level
6181
6424
  */
6182
6425
  Rive.prototype.setNumberStateAtPath = function (inputName, value, path) {
6426
+ warnOnce(stateMachineInputsDeprecationWarning);
6183
6427
  var input = this.retrieveInputAtPath(inputName, path);
6184
6428
  if (!input)
6185
6429
  return;
@@ -6192,10 +6436,15 @@ var Rive = /** @class */ (function () {
6192
6436
  };
6193
6437
  /**
6194
6438
  * Fire the trigger with the provided name at the given path
6439
+ * @deprecated State machine inputs are deprecated: use data binding
6440
+ * properties instead. See
6441
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
6442
+ * for how to migrate.
6195
6443
  * @param input the state machine input name
6196
6444
  * @param path the path the input is located at an artboard level
6197
6445
  */
6198
6446
  Rive.prototype.fireStateAtPath = function (inputName, path) {
6447
+ warnOnce(stateMachineInputsDeprecationWarning);
6199
6448
  var input = this.retrieveInputAtPath(inputName, path);
6200
6449
  if (!input)
6201
6450
  return;
@@ -6243,8 +6492,13 @@ var Rive = /** @class */ (function () {
6243
6492
  *
6244
6493
  * @remarks
6245
6494
  * If the text run cannot be found at the specified path, a warning will be logged to the console.
6495
+ *
6496
+ * @deprecated Text run APIs are deprecated: use data binding instead. See
6497
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
6498
+ * for how to migrate.
6246
6499
  */
6247
6500
  Rive.prototype.getTextRunValueAtPath = function (textName, path) {
6501
+ warnOnce(textRunsDeprecationWarning);
6248
6502
  var run = this.retrieveTextAtPath(textName, path);
6249
6503
  if (!run) {
6250
6504
  console.warn("Could not get text with name: '".concat(textName, "', at path:'").concat(path, "'"));
@@ -6269,8 +6523,13 @@ var Rive = /** @class */ (function () {
6269
6523
  *
6270
6524
  * @remarks
6271
6525
  * If the text run cannot be found at the specified path, a warning will be logged to the console.
6526
+ *
6527
+ * @deprecated Text run APIs are deprecated: use data binding instead. See
6528
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
6529
+ * for how to migrate.
6272
6530
  */
6273
6531
  Rive.prototype.setTextRunValueAtPath = function (textName, value, path) {
6532
+ warnOnce(textRunsDeprecationWarning);
6274
6533
  var run = this.retrieveTextAtPath(textName, path);
6275
6534
  if (!run) {
6276
6535
  console.warn("Could not set text with name: '".concat(textName, "', at path:'").concat(path, "'"));
@@ -6379,10 +6638,26 @@ var Rive = /** @class */ (function () {
6379
6638
  });
6380
6639
  /**
6381
6640
  * Subscribe to Rive-generated events
6641
+ *
6642
+ * Note: subscribing to {@link EventType.RiveEvent},
6643
+ * {@link EventType.StateChange}, or {@link EventType.Loop} is deprecated;
6644
+ * use data binding instead. See
6645
+ * {@link https://rive.app/docs/runtimes/web/rive-events} (Rive Events) and
6646
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide} for how
6647
+ * to migrate Rive graphics to a data binding workflow instead.
6382
6648
  * @param type the type of event to subscribe to
6383
6649
  * @param callback callback to fire when the event occurs
6384
6650
  */
6385
6651
  Rive.prototype.on = function (type, callback) {
6652
+ if (type === EventType.RiveEvent) {
6653
+ warnOnce(riveEventsDeprecationWarning);
6654
+ }
6655
+ else if (type === EventType.StateChange) {
6656
+ warnOnce(stateChangeEventsDeprecationWarning);
6657
+ }
6658
+ else if (type === EventType.Loop) {
6659
+ warnOnce(loopEventsDeprecationWarning);
6660
+ }
6386
6661
  this.eventManager.add({
6387
6662
  type: type,
6388
6663
  callback: callback,