@rive-app/webgl2-threads 0.0.0-stage → 2.47.1

package/utils/keyMap.d.ts

@@ -0,0 +1,141 @@
+export declare const Key: {
+    readonly space: 32;
+    readonly apostrophe: 39;
+    readonly comma: 44;
+    readonly minus: 45;
+    readonly period: 46;
+    readonly slash: 47;
+    readonly key0: 48;
+    readonly key1: 49;
+    readonly key2: 50;
+    readonly key3: 51;
+    readonly key4: 52;
+    readonly key5: 53;
+    readonly key6: 54;
+    readonly key7: 55;
+    readonly key8: 56;
+    readonly key9: 57;
+    readonly semicolon: 59;
+    readonly equal: 61;
+    readonly a: 65;
+    readonly b: 66;
+    readonly c: 67;
+    readonly d: 68;
+    readonly e: 69;
+    readonly f: 70;
+    readonly g: 71;
+    readonly h: 72;
+    readonly i: 73;
+    readonly j: 74;
+    readonly k: 75;
+    readonly l: 76;
+    readonly m: 77;
+    readonly n: 78;
+    readonly o: 79;
+    readonly p: 80;
+    readonly q: 81;
+    readonly r: 82;
+    readonly s: 83;
+    readonly t: 84;
+    readonly u: 85;
+    readonly v: 86;
+    readonly w: 87;
+    readonly x: 88;
+    readonly y: 89;
+    readonly z: 90;
+    readonly leftBracket: 91;
+    readonly backslash: 92;
+    readonly rightBracket: 93;
+    readonly graveAccent: 96;
+    readonly world1: 161;
+    readonly world2: 162;
+    readonly escape: 256;
+    readonly enter: 257;
+    readonly tab: 258;
+    readonly backspace: 259;
+    readonly insert: 260;
+    readonly deleteKey: 261;
+    readonly right: 262;
+    readonly left: 263;
+    readonly down: 264;
+    readonly up: 265;
+    readonly pageUp: 266;
+    readonly pageDown: 267;
+    readonly home: 268;
+    readonly end: 269;
+    readonly capsLock: 280;
+    readonly scrollLock: 281;
+    readonly numLock: 282;
+    readonly printScreen: 283;
+    readonly pause: 284;
+    readonly f1: 290;
+    readonly f2: 291;
+    readonly f3: 292;
+    readonly f4: 293;
+    readonly f5: 294;
+    readonly f6: 295;
+    readonly f7: 296;
+    readonly f8: 297;
+    readonly f9: 298;
+    readonly f10: 299;
+    readonly f11: 300;
+    readonly f12: 301;
+    readonly f13: 302;
+    readonly f14: 303;
+    readonly f15: 304;
+    readonly f16: 305;
+    readonly f17: 306;
+    readonly f18: 307;
+    readonly f19: 308;
+    readonly f20: 309;
+    readonly f21: 310;
+    readonly f22: 311;
+    readonly f23: 312;
+    readonly f24: 313;
+    readonly f25: 314;
+    readonly kp0: 320;
+    readonly kp1: 321;
+    readonly kp2: 322;
+    readonly kp3: 323;
+    readonly kp4: 324;
+    readonly kp5: 325;
+    readonly kp6: 326;
+    readonly kp7: 327;
+    readonly kp8: 328;
+    readonly kp9: 329;
+    readonly kpDecimal: 330;
+    readonly kpDivide: 331;
+    readonly kpMultiply: 332;
+    readonly kpSubtract: 333;
+    readonly kpAdd: 334;
+    readonly kpEnter: 335;
+    readonly kpEqual: 336;
+    readonly leftShift: 340;
+    readonly leftControl: 341;
+    readonly leftAlt: 342;
+    readonly leftSuper: 343;
+    readonly rightShift: 344;
+    readonly rightControl: 345;
+    readonly rightAlt: 346;
+    readonly rightSuper: 347;
+    readonly menu: 348;
+};
+export declare const KeyModifiers: {
+    readonly none: 0;
+    readonly shift: number;
+    readonly ctrl: number;
+    readonly alt: number;
+    readonly meta: number;
+};
+/**
+ * Maps a KeyboardEvent to a Rive key, or null if Rive has no equivalent.
+ *
+ * Resolves the logical key: what the user's layout labels the key, ignoring
+ * Shift, so a listener on "A" fires on AZERTY's A too. `event.key` is preferred;
+ * `event.code` is the fallback when `key` isn't a plain unshifted character
+ * (shifted symbols, Option/AltGr output, non-Latin letters, dead keys).
+ * Digit-row and numpad keys skip the character lookup so AZERTY's digit row
+ * still reports digits and numpad digits stay distinct from the digit row.
+ */
+export declare function keyboardEventToRiveKey(event: KeyboardEvent): number | null;
+export declare function modifiersFromEvent(event: KeyboardEvent): number;

package/utils/registerKeyboardInteractions.d.ts

@@ -0,0 +1,174 @@
+import * as rc from "../rive_advanced.mjs";
+import { TextInputProxy } from "./textInputProxy";
+export interface KeyboardInteractionsParams {
+    canvas: HTMLCanvasElement;
+    stateMachine: rc.StateMachineInstance;
+    /**
+     * Whether this canvas has focus nodes that should participate in tab traversal.
+     * When true, Tab/Shift+Tab will be intercepted and routed to the Rive focus manager.
+     * Tab is released to the page only when focusNext() returns false and Rive no longer holds
+     * focus; a Stop edge also returns false but keeps focus, so Tab stays trapped.
+     */
+    hasFocusNodes: boolean;
+    /**
+     * Optional accessibility overlay that should be treated as part of this Rive
+     * instance's focus domain. This is lazy because the overlay may be created
+     * after keyboard listeners are registered.
+     */
+    getOverlayElement?: () => HTMLElement | null;
+}
+/**
+ * Tracks the relationship between DOM focus inside this Rive focus domain (canvas or semantic overlay)
+ * and Rive's internal focus for the current focus session.
+ *
+ * NotFocused   — DOM focus left the domain, Rive released focus internally, or Tab walked
+ *                off the end of the tree. Keyboard input isn't ours, so Tab is ignored and
+ *                reaches the next page element.
+ * EntryPending — DOM focus is inside the domain but Rive holds no node yet, so the next Tab
+ *                enters the focus tree. Set by pointer focus on the canvas, by assistive technology (AT) focus landing
+ *                in the overlay, and by keyboard focus whose entry attempt found no eligible node.
+ * RiveFocused  — a Rive node holds focus. Tab/Shift+Tab route to the Rive focus manager and stay
+ *                inside the domain until either Rive reports focus ended (pollFocusState) or
+ *                Tab walks off the edge of the tree (focusNext()/focusPrevious() returns false and
+ *                Rive no longer holds focus).
+ *
+ * Keyboard focus on the canvas enters the tree immediately: onCanvasFocus infers direction from
+ * where focus came from and goes straight to RiveFocused when a node accepts.
+ */
+export declare enum FocusSessionState {
+    NotFocused = "notFocused",
+    EntryPending = "entryPending",
+    RiveFocused = "riveFocused"
+}
+/**
+ * Manages keyboard and DOM focus interactions for Rive's focus domain (<canvas>, semantic
+ * overlay, text input proxy). Owns the proxy and the text input session state.
+ * Because keyboard events can apply on either part of the domain, we need to track what events we should
+ * handle/intercept, and when to release focus back to the page outside of the domain.
+ *
+ * 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.
+ */
+export declare class KeyboardInteractions {
+    focusSessionState: FocusSessionState;
+    private canvas;
+    private mainSm;
+    private hasFocusNodes;
+    /** Cached callback that returns the accessibility overlay element once created. */
+    private getOverlayElement?;
+    /** Whether the canvas currently has browser DOM focus. */
+    private canvasHasFocus;
+    /** After Tab exits the last Rive node, ignore keydowns until focus re-enters the focus domain. */
+    private focusDomainReleased;
+    /** Overlay element currently wired with focusin/keydown listeners, if any. */
+    private currentOverlayElement;
+    /** Canvas parent (or document) watched for focusin to attach overlay listeners lazily. */
+    private focusDomainHost;
+    /** Codes whose keydown an overlay widget took, so their keyup is skipped too. */
+    private claimedKeyCodes;
+    private readonly inputProxy;
+    private textInputSessionActive;
+    constructor({ canvas, stateMachine, hasFocusNodes, getOverlayElement, }: KeyboardInteractionsParams);
+    isTextInputSessionActive(): boolean;
+    /** Session active and the proxy holds DOM focus. */
+    isEditingHostFocused(): boolean;
+    /** @param focusProxy move DOM focus to the proxy; false leaves it where it is. */
+    beginTextInputSession(focusProxy: boolean): void;
+    /** @param fromBlur focus is already leaving; don't park it on the canvas. */
+    endTextInputSession(fromBlur?: boolean): void;
+    /** Must run synchronously in the pointer gesture or mobile keyboards won't open. */
+    summonForPointer(): void;
+    /** The text-input proxy, for the semantics layer to decorate while editing. */
+    get editingHost(): TextInputProxy;
+    /**
+     * The proxy is always empty: copy Rive's selection; always preventDefault.
+     */
+    private onCopy;
+    private handleProxyBlur;
+    /**
+     * 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
+     */
+    setFocusSessionState(state: FocusSessionState): void;
+    /**
+     * 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. This cannot resurrect a session that a DOM blur ended,
+     * because onCanvasBlur clears Rive's focus alongside it.
+     */
+    notifyRiveFocused(): void;
+    /**
+     * 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.
+     */
+    onCanvasFocus: (event: FocusEvent) => void;
+    /**
+     * Marks internal state that the canvas has lost DOM focus. Do not actually clear
+     * Rive focus though if:
+     * 1. DOM focus is still within Rive domain (i.e., semantic overlay)
+     * 2. Document just lost focus (i.e. tab switching)
+     *
+     * When we're not in either of those buckets, it's safe to call `clearFocus()` on the SMI.
+     */
+    onCanvasBlur: (event: FocusEvent) => void;
+    /** Blur into the focus domain, or the whole document losing focus (tab/window switch). */
+    private blurStaysWithRive;
+    /**
+     * Assistive technology (AT) focus landing inside the overlay is DOM focus inside the Rive focus domain, so open a
+     * session even when no Rive node holds focus yet. shouldRiveHandleKeyEvent treats NotFocused
+     * as authoritative, so without this the overlay's Tab keydowns reach onKeyDown and get dropped
+     * at that gate — the browser would move focus out of Rive instead of to the next focus node.
+     */
+    private onOverlayFocusIn;
+    /** Overlay listeners attach lazily, so the first focusin only ever lands here. */
+    private onFocusDomainHostFocusIn;
+    /**
+     * Handles keydown events in the Rive focus domain. We route certain keys to different functions, with the following
+     * fallback behavior:
+     * 1. Tab/Shift+Tab - check if keyInput() takes this key, if not, call focusNext/Previous traversal if there are focus nodes
+     * 2. Check - if a semantic overlay element's key handler claimed the event, don't intercept the key event further
+     * 3. Send key to `keyInput()` on Rive state machine if applicable.
+     * 4. If the keyInput returned false, and the key is directional arrow keys, call directional focus methods on state machine
+     * 5. Printables: in a session the proxy's input event supplies text; otherwise textInput().
+     *    A printable fires both keyInput and textInput even if a listener claims it.
+     * @param event KeyboardEvent
+     * @returns void
+     */
+    onKeyDown: (event: KeyboardEvent) => void;
+    onKeyUp: (event: KeyboardEvent) => void;
+    /** Arrow keys map to directional focus; anything else is not a focus move. */
+    private focusInDirection;
+    /**
+     * Determine if Rive should handle keyboard input. If session state is `NotFocused` - no.
+     * DOM focus stays parked on the canvas after Rive releases focus internally, and that Tab
+     * has to reach the page rather than re-enter the tree.
+     *
+     * Otherwise, the event still has to belong to Rive:
+     * 1. If the current DOM focus is in Rive domain (canvas or semantic overlay)
+     * 2. If the target for the key input is for the semantic overlay, or the canvas
+     */
+    private shouldRiveHandleKeyEvent;
+    /** DOM that counts as inside Rive for focus: canvas, overlay subtree, text-input proxy. */
+    isInFocusDomain(target: EventTarget | null): boolean;
+    /** Overlay only (excludes the canvas) — the accessibility overlay subtree. */
+    private isInOverlay;
+    private syncOverlayListener;
+    /**
+     * 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.
+     */
+    private isKeyboardDrivenFocus;
+    private cameFromBeforeCanvas;
+    cleanup(): void;
+}

package/utils/registerTouchInteractions.d.ts

@@ -0,0 +1,25 @@
+import * as rc from "../rive_advanced.mjs";
+export interface TouchInteractionsParams {
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    artboard: rc.Artboard;
+    stateMachines: rc.StateMachineInstance[];
+    renderer: rc.Renderer;
+    rive: rc.RiveCanvas;
+    fit: rc.Fit;
+    alignment: rc.Alignment;
+    isTouchScrollEnabled?: boolean;
+    dispatchPointerExit?: boolean;
+    enableMultiTouch?: boolean;
+    layoutScaleFactor?: number;
+    advanceAndDrain: (elapsedTime: number, options?: {
+        pointerDown?: boolean;
+    }) => void;
+    summonKeyboard?: () => void;
+    isTextProxyFocused?: () => boolean;
+}
+/**
+ * Registers mouse move/up/down and wheel callback handlers on the canvas to send meaningful
+ * coordinates to the state machine pointer move/up/down/scroll functions based on cursor
+ * interaction
+ */
+export declare const registerTouchInteractions: ({ canvas, artboard, stateMachines, renderer, rive, fit, alignment, isTouchScrollEnabled, dispatchPointerExit, enableMultiTouch, layoutScaleFactor, advanceAndDrain, summonKeyboard, isTextProxyFocused, }: TouchInteractionsParams) => () => void;

package/utils/riveFont.d.ts

@@ -0,0 +1,15 @@
+import type { FontWrapper } from "./finalizationRegistry";
+export type FallbackFontsCallback = (missingGlyph: number, weight: number) => FontWrapper | FontWrapper[] | null | undefined;
+export declare class RiveFont {
+    private static _fallbackFontCallback;
+    private constructor();
+    /**
+     * Set a callback to dynamically set a list of fallback fonts based on the missing glyph and/or style of the default font.
+     * Set null to clear the callback.
+     * @param fontCallback Callback to set a list of fallback fonts.
+     */
+    static setFallbackFontCallback(fontCallback: FallbackFontsCallback | null): void;
+    private static _fontToPtr;
+    private static _getFallbackPtr;
+    private static _wireFallbackProc;
+}

package/utils/sanitizeUrl.d.ts

@@ -0,0 +1,2 @@
+export declare const BLANK_URL = "about:blank";
+export declare function sanitizeUrl(url?: string): string;

package/utils/textInputProxy.d.ts

@@ -0,0 +1,61 @@
+export interface TextInputProxyParams {
+    /** Where to mount the proxy — the canvas's parent so it scrolls/positions with it. */
+    container: HTMLElement;
+    /** The Rive canvas, used to position the proxy over it (iOS scroll-jump avoidance) and for domain checks. */
+    canvas: HTMLElement;
+    /** Forward committed text (typing, IME/dead-key commits, paste) into the focus tree. */
+    textInput: (text: string) => boolean;
+    /** Physical key events on the proxy route back through KeyboardInteractions' shared policy. */
+    onKeyDown: (event: KeyboardEvent) => void;
+    onKeyUp: (event: KeyboardEvent) => void;
+    /** The field is empty; fill the clipboard from Rive's selection. */
+    onCopy: (event: ClipboardEvent) => void;
+    /** Called when the proxy loses DOM focus; the receiver decides whether to tear the session down. */
+    onBlur: (relatedTarget: EventTarget | null) => void;
+}
+/**
+ * Invisible per-instance <input> capturing IME/dead-key/paste text; focusable inside a
+ * gesture to raise mobile keyboards. Always empty: C++ owns value and caret. Decorated
+ * for AT only while it holds DOM focus.
+ */
+export declare class TextInputProxy {
+    private params;
+    private element;
+    private composing;
+    private decoratedKeys;
+    private lastLeft;
+    private lastTop;
+    constructor(params: TextInputProxyParams);
+    private listeners;
+    private createElement;
+    private positionOverCanvas;
+    /** Re-sync before input: the canvas may have scrolled since the session began. */
+    private reposition;
+    private onCompositionStart;
+    private onCompositionEnd;
+    private onInput;
+    /**
+     * Forward the field's text to Rive and clear it.
+     *
+     * TODO: iOS won't autorepeat Backspace in an empty field (needs a text mirror).
+     * */
+    private commit;
+    private onPaste;
+    private onBlur;
+    /** Clear any transient value and decoration. Does not blur the element. */
+    endSession(): void;
+    /** Must be called synchronously inside a gesture on iOS to raise the keyboard. */
+    focus(): void;
+    hasDomFocus(): boolean;
+    owns(target: EventTarget | null): boolean;
+    /** See EditingHost.decorate. */
+    decorate(attrs: Record<string, string | null>): void;
+    /**
+     * type=password for obscured fields so AT doesn't echo keys.
+     * TODO: source "type" from Core, not semantics.
+     */
+    setSecure(secure: boolean): void;
+    /** Drop all decoration and return to the AT-invisible baseline. */
+    resetDecoration(): void;
+    cleanup(): void;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.