@rive-app/canvas-single 2.41.0 → 2.42.0

package/rive_advanced.mjs.d.ts

@@ -42,18 +42,42 @@ export interface RiveCanvas {
   // Returns a pointer value to the FontWrapper
   setFallbackFontCallback: (callback: (missingGlyph: number, fallbackFontIndex: number, weight: number) => number | null) => void;
 
+  /**
+   * @experimental Creates a deferred recording session. Only present in builds
+   * with deferred rendering compiled in, so always feature-detect it.
+   *
+   * The session is a Factory: pass it to `load()` and to the decode APIs of the
+   * assets that belong to that file, and attach it to exactly one renderer with
+   * `attachSession()`.
+   *
+   * Teardown order should be:
+   *   1. release the file the session imported,
+   *   2. `detachSession()` on the renderer it is attached to,
+   *   3. `delete()` the session.
+   * Deleting an attached session leaves the renderer pointing at freed memory
+   * on the canvas2d build — the next frame either draws from freed heap or
+   * throws `Cannot pass deleted object`. Detach first, always, even when the
+   * renderer is about to be deleted too.
+   *
+   * @returns A DeferredSession, or undefined if the session could not be created
+   */
+  makeDeferredSession?(): DeferredSession | undefined;
+
   /**
    * Loads a Rive file for the runtime and returns a Rive-specific File class
    *
    * @param buffer - Array buffer of a Rive file
    * @param assetLoader - FileAssetLoader used to optionally customize loading of font and image assets
    * @param enableRiveAssetCDN - boolean flag to allow loading assets from the Rive CDN, enabled by default.
+   * @param session - @experimental Deferred session to import through. The file's mode is fixed
+   * at import: pass null (the default) for an immediate file.
    * @returns A Promise for a Rive File class
    */
   load(
     buffer: Uint8Array,
     assetLoader?: FileAssetLoader,
     enableRiveAssetCDN?: boolean,
+    session?: DeferredSession | null,
   ): Promise<File>;
 
   /**
@@ -141,6 +165,24 @@ export interface RiveCanvas {
 // RENDERER //
 //////////////
 
+/**
+ * @experimental A deferred recording session, owned by the RiveFile that imported
+ * through it.
+ *
+ * A session records for one ore/GL context, so it binds to exactly one renderer
+ * and can never rebind once detached. It must outlive the file it imported.
+ */
+export declare class DeferredSession {
+  delete(): void;
+  /**
+   * @experimental Whether anything was recorded into this session's stream this
+   * frame, including ore content the artboard's own change flag cannot see.
+   * Only meaningful before the renderer clears: clear opens a recording window
+   * that marks the stream, so a later read reports every frame as recorded.
+   */
+  recordedThisFrame(): boolean;
+}
+
 /**
  * Rive wrapper around a rendering context for a canvas element, implementing a subset of the APIs
  * from the rendering context interface
@@ -164,12 +206,19 @@ export declare class RendererWrapper {
   drawPath(path: RenderPath, paint: RenderPaint): void;
   clipPath(path: RenderPath): void;
   /**
-   * Calls the context's clearRect() function to clear the entire canvas. Crucial to call
-   * this at the start of the render loop to clear the canvas before drawing the next frame
+   * Begins a frame. Crucial to call this at the start of the render loop: besides clearing
+   * the canvas, it registers the renderer so that its queued draws actually get flushed.
    *
-   * For the underlying API, check
+   * Pass clear=false to draw on top of whatever the canvas already holds instead of
+   * starting from a blank one.
+   *
+   * For the underlying clear, check
    * https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/clearRect
    */
+  beginFrame(clear?: boolean): void;
+  /**
+   * @deprecated Use {@link beginFrame} instead. Equivalent to `beginFrame(true)`.
+   */
   clear(): void;
   delete(): void;
   flush(): void;
@@ -180,11 +229,38 @@ export declare class RendererWrapper {
    * performing any WASM teardown that frees resources
    */
   bindContext?(): void;
+  /**
+   * @experimental Binds a deferred session to this renderer's context: draws record
+   * into the session and replay at flush. Absent on renderers that cannot replay a
+   * session (an offscreen renderer, or a build without deferred support).
+   *
+   * @param session - The session the file was imported through
+   * @returns false if this renderer already has a session, or the session is (or was)
+   * bound elsewhere. Attaching is once per session: re-import into a fresh session instead
+   */
+  attachSession?(session: DeferredSession): boolean;
+  /**
+   * @experimental Releases the attached session's replay state. The session can never
+   * be attached again.
+   */
+  detachSession?(): void;
+  /**
+   * @experimental Whether a deferred session is currently attached.
+   */
+  deferredActive?(): boolean;
 }
 
 export declare class RenderPathWrapper {
   reset(): void;
-  addPath(path: CommandPath, transform: Mat2D): void;
+  addPath(
+    path: CommandPath,
+    xx: number,
+    xy: number,
+    yx: number,
+    yy: number,
+    tx: number,
+    ty: number,
+  ): void;
   fillRule(value: FillRule): void;
   moveTo(x: number, y: number): void;
   lineTo(x: number, y: number): void;
@@ -233,11 +309,11 @@ export declare class Renderer extends RendererWrapper {
   ): void;
 }
 
-export declare class CommandPath {}
+export declare class CommandPath { }
 
-export declare class RenderPath extends RenderPathWrapper {}
+export declare class RenderPath extends RenderPathWrapper { }
 
-export declare class RenderPaint extends RenderPaintWrapper {}
+export declare class RenderPaint extends RenderPaintWrapper { }
 
 /////////////////////
 // CANVAS RENDERER //
@@ -287,7 +363,7 @@ export declare class CanvasRenderPaint extends RenderPaint {
   ): void;
 }
 
-export declare class CanvasRenderPath extends RenderPath {}
+export declare class CanvasRenderPath extends RenderPath { }
 
 export interface CanvasRenderFactory {
   makeRenderPaint(): CanvasRenderPaint;
@@ -304,8 +380,16 @@ export class Audio {
 export interface AudioCallback {
   (audio: Audio): void;
 }
+/**
+ * The trailing session is the one of the deferred file the asset is bound into;
+ * an asset decoded against any other factory is dropped when that file draws.
+ */
 export interface DecodeAudio {
-  (bytes: Uint8Array, callback: AudioCallback): void;
+  (
+    bytes: Uint8Array,
+    callback: AudioCallback,
+    session?: DeferredSession | null,
+  ): void;
 }
 export class ImageInternal {
   unref(): void;
@@ -318,7 +402,11 @@ export interface ImageCallback {
   (image: Image): void;
 }
 export interface DecodeImage {
-  (bytes: Uint8Array, callback: ImageCallback): void;
+  (
+    bytes: Uint8Array,
+    callback: ImageCallback,
+    session?: DeferredSession | null,
+  ): void;
 }
 export class FontInternal {
   unref(): void;
@@ -333,7 +421,11 @@ export interface FontCallback {
   (font: Font): void;
 }
 export interface DecodeFont {
-  (bytes: Uint8Array, callback: FontCallback): void;
+  (
+    bytes: Uint8Array,
+    callback: FontCallback,
+    session?: DeferredSession | null,
+  ): void;
 }
 
 //////////
@@ -1202,11 +1294,11 @@ export declare class DataEnum {
   get values(): string[];
 }
 
-export declare class SMIBool {}
+export declare class SMIBool { }
 
-export declare class SMINumber {}
+export declare class SMINumber { }
 
-export declare class SMITrigger {}
+export declare class SMITrigger { }
 
 ///////////
 // ENUMS //
@@ -1371,7 +1463,12 @@ export declare class FileAsset {
   isFont: boolean;
   cdnUuid: string;
 
-  decode(bytes: Uint8Array): void;
+  /**
+   * @param session - @experimental The session of the deferred file this asset belongs
+   * to, null for an immediate file. Wired by the runtime; pass it explicitly only when
+   * calling the native asset directly.
+   */
+  decode(bytes: Uint8Array, session?: DeferredSession | null): void;
   get nativeAsset(): FileAssetInternal;
 }
 
@@ -1388,7 +1485,7 @@ export declare class FileAssetInternal {
   isFont: boolean;
   cdnUuid: string;
 
-  decode(bytes: Uint8Array): void;
+  decode(bytes: Uint8Array, session?: DeferredSession | null): void;
 }
 
 export declare class AudioAssetInternal extends FileAssetInternal {
@@ -1428,7 +1525,7 @@ export declare class FontAsset extends FileAsset {
   setFont(font: Font | FontWrapper): void;
 }
 
-export declare class FileAssetLoader {}
+export declare class FileAssetLoader { }
 
 export declare class CustomFileAssetLoader extends FileAssetLoader {
   constructor({ loadContents }: { loadContents: Function });

package/semantics/index.d.ts

@@ -1,5 +1,5 @@
 export { SemanticTreeModel } from "./semanticTreeModel";
 export { AccessibilityOverlay } from "./accessibilityOverlay";
 export type { AccessibilityOverlayOptions } from "./accessibilityOverlay";
-export { SemanticRole, SemanticState, SemanticTrait, SemanticActionType, SemanticMode, hasState, hasTrait, roleName, stateNames, traitNames, } from "./types";
+export { SemanticRole, SemanticState, SemanticCheckState, SemanticTrait, SemanticActionType, SemanticMode, CHECK_STATE_OFFSET, CHECK_STATE_MASK, checkStateOf, hasState, hasTrait, roleName, stateNames, traitNames, } from "./types";
 export type { SemanticsDiffNode, SemanticsDiff, SemanticNodeData, RiveSemanticsOptions, } from "./types";

package/semantics/types.d.ts

@@ -25,8 +25,6 @@ export declare const SemanticState: {
     readonly None: 0;
     readonly Expanded: number;
     readonly Selected: number;
-    readonly Checked: number;
-    readonly Mixed: number;
     readonly Toggled: number;
     readonly Required: number;
     readonly Disabled: number;
@@ -39,6 +37,21 @@ export declare const SemanticState: {
     readonly Multiline: number;
 };
 export declare function hasState(flags: number, state: number): boolean;
+export declare const SemanticCheckState: {
+    readonly Unchecked: 0;
+    readonly Checked: 1;
+    readonly Mixed: 2;
+};
+export type SemanticCheckState = (typeof SemanticCheckState)[keyof typeof SemanticCheckState];
+/** Bit offset of the check field within stateFlags. */
+export declare const CHECK_STATE_OFFSET = 2;
+/** Mask of the check field within stateFlags. */
+export declare const CHECK_STATE_MASK: number;
+/**
+ * Decodes the check field out of `flags`. The field is two bits. Returns 0, 1, or 2
+ * per the mapping in SemanticCheckState.
+ */
+export declare function checkStateOf(flags: number): SemanticCheckState;
 /**
  * Controls when the instance builds semantic trees and accessibility overlays.
  *

package/utils/finalizationRegistry.d.ts

@@ -4,9 +4,11 @@ interface Finalizable {
 }
 declare class FileFinalizer implements Finalizable {
     private _file;
+    private _session;
     selfUnref: boolean;
-    constructor(file: rc.File);
+    constructor(file: rc.File, session?: rc.DeferredSession | null);
     unref(): void;
+    release(): void;
 }
 declare class AssetWrapper implements rc.FinalizableTarget {
     selfUnref: boolean;
@@ -34,7 +36,8 @@ export type AssetLoadCallbackWrapper = (asset: rc.FileAssetInternal, bytes: Uint
 declare class CustomFileAssetLoaderWrapper {
     assetLoader: rc.CustomFileAssetLoader;
     _assetLoaderCallback: AssetLoadCallbackWrapper;
-    constructor(runtime: rc.RiveCanvas, loaderCallback: AssetLoadCallbackWrapper);
+    _session: rc.DeferredSession | null;
+    constructor(runtime: rc.RiveCanvas, loaderCallback: AssetLoadCallbackWrapper, session?: rc.DeferredSession | null);
     loadContents(asset: rc.FileAsset, bytes: any): false | Boolean;
 }
 /**
@@ -43,7 +46,8 @@ declare class CustomFileAssetLoaderWrapper {
  */
 declare class FileAssetWrapper {
     _nativeFileAsset: rc.FileAssetInternal;
-    constructor(nativeAsset: rc.FileAssetInternal);
+    _session: rc.DeferredSession | null;
+    constructor(nativeAsset: rc.FileAssetInternal, session?: rc.DeferredSession | null);
     decode(bytes: Uint8Array): void;
     get name(): string;
     get fileExtension(): string;