@motion-core/motion-gpu 0.3.0 → 0.4.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Svelte](https://img.shields.io/badge/Svelte-5-orange.svg)](https://svelte.dev)
+[![React](https://img.shields.io/badge/React-18%2B-149eca.svg)](https://react.dev)
 [![WebGPU](https://img.shields.io/badge/Shaders-WGSL-blueviolet.svg)](https://gpuweb.github.io/gpuweb/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue.svg)](https://www.typescriptlang.org)
 [![npm](https://img.shields.io/badge/npm-@motion--core%2Fmotion--gpu-red.svg)](https://www.npmjs.com/package/@motion-core/motion-gpu)
@@ -12,7 +13,7 @@
 
 **A tiny WebGPU runtime for writing Shadertoy-style fullscreen shaders in pure WGSL.**
 
-`@motion-core/motion-gpu` ships a framework-agnostic core plus a Svelte 5 adapter for building fullscreen shader pipelines using WebGPU and WGSL.
+`@motion-core/motion-gpu` ships a framework-agnostic core plus Svelte 5 and React adapters for building fullscreen shader pipelines using WebGPU and WGSL.
 It provides a minimal runtime loop, scheduler, and render graph designed specifically for fragment-driven GPU programs.
 
 Unlike general-purpose 3D engines, Motion GPU focuses on a very narrow problem: **running fullscreen fragment shaders and multi-pass GPU pipelines**.
@@ -119,6 +120,39 @@ Also exports runtime/core types:
 
 ---
 
+## React adapter
+
+`@motion-core/motion-gpu/react` exposes the runtime API for React:
+
+- `FragCanvas`
+- `defineMaterial`
+- `useMotionGPU`
+- `useFrame`
+- `useTexture`
+- `ShaderPass`
+- `BlitPass`
+- `CopyPass`
+
+Also exports runtime/core types:
+
+- uniforms
+- textures
+- render passes
+- scheduler
+- loader types
+
+---
+
+`@motion-core/motion-gpu/react/advanced` re-exports everything above, plus:
+
+- `useMotionGPUUserContext`
+- `useSetMotionGPUUserContext`
+- `setMotionGPUUserContext`
+- `applySchedulerPreset`
+- `captureSchedulerDebugSnapshot`
+
+---
+
 ## Framework-agnostic core
 
 `@motion-core/motion-gpu` (and explicit alias `@motion-core/motion-gpu/core`) exposes adapter-building primitives:
@@ -144,6 +178,7 @@ Also exports runtime/core types:
 # Requirements
 
 - Svelte 5 is required only for the Svelte adapter entrypoints (`/svelte`, `/svelte/advanced`)
+- React 18+ is required only for the React adapter entrypoints (`/react`, `/react/advanced`)
 - A browser/runtime with WebGPU support
 - Secure context (`https://` or `localhost`)
 
@@ -188,6 +223,30 @@ fn frag(uv: vec2f) -> vec4f {
 
 ---
 
+### React equivalent
+
+```tsx
+import { FragCanvas, defineMaterial } from '@motion-core/motion-gpu/react';
+
+const material = defineMaterial({
+	fragment: `
+fn frag(uv: vec2f) -> vec4f {
+	return vec4f(uv.x, uv.y, 0.25, 1.0);
+}
+`
+});
+
+export function App() {
+	return (
+		<div style={{ width: '100vw', height: '100vh' }}>
+			<FragCanvas material={material} />
+		</div>
+	);
+}
+```
+
+---
+
 ## 2. Add animated uniforms via `useFrame`
 
 ```svelte
@@ -225,6 +284,18 @@ fn frag(uv: vec2f) -> vec4f {
 </script>
 ```
 
+```tsx
+import { useFrame } from '@motion-core/motion-gpu/react';
+
+export function Runtime() {
+	useFrame((state) => {
+		state.setUniform('uTime', state.time);
+	});
+
+	return null;
+}
+```
+
 ---
 
 # Core Runtime Model

package/dist/core/material-preprocess.d.ts

@@ -44,11 +44,11 @@ export interface PreprocessedMaterialFragment {
 /**
  * Validates and normalizes define entries.
  */
-export declare function normalizeDefines(defines: MaterialDefines | undefined): MaterialDefines;
+export declare function normalizeDefines<TDefineKey extends string>(defines: MaterialDefines<TDefineKey> | undefined): MaterialDefines<TDefineKey>;
 /**
  * Validates include map identifiers and source chunks.
  */
-export declare function normalizeIncludes(includes: MaterialIncludes | undefined): MaterialIncludes;
+export declare function normalizeIncludes<TIncludeKey extends string>(includes: MaterialIncludes<TIncludeKey> | undefined): MaterialIncludes<TIncludeKey>;
 /**
  * Converts one define declaration to WGSL `const`.
  */
@@ -56,8 +56,8 @@ export declare function toDefineLine(key: string, value: MaterialDefineValue): s
 /**
  * Preprocesses material fragment with deterministic define/include expansion and line mapping.
  */
-export declare function preprocessMaterialFragment(input: {
+export declare function preprocessMaterialFragment<TDefineKey extends string, TIncludeKey extends string>(input: {
     fragment: string;
-    defines?: MaterialDefines;
-    includes?: MaterialIncludes;
+    defines?: MaterialDefines<TDefineKey>;
+    includes?: MaterialIncludes<TIncludeKey>;
 }): PreprocessedMaterialFragment;

package/dist/core/material-preprocess.js

@@ -44,10 +44,7 @@ export function normalizeDefines(defines) {
             continue;
         }
         const normalized = normalizeTypedDefine(name, value);
-        resolved[name] = Object.freeze({
-            type: normalized.type,
-            value: normalized.value
-        });
+        resolved[name] = Object.freeze(normalized);
     }
     return resolved;
 }

package/dist/core/material.d.ts

@@ -5,16 +5,25 @@ import type { TextureDefinitionMap, UniformMap } from './types.js';
 /**
  * Typed compile-time define declaration.
  */
-export interface TypedMaterialDefineValue {
+export type TypedMaterialDefineValue = {
     /**
      * WGSL scalar type.
      */
-    type: 'bool' | 'f32' | 'i32' | 'u32';
+    type: 'bool';
     /**
      * Literal value for the selected WGSL type.
      */
-    value: boolean | number;
-}
+    value: boolean;
+} | {
+    /**
+     * WGSL scalar type.
+     */
+    type: 'f32' | 'i32' | 'u32';
+    /**
+     * Literal value for the selected WGSL type.
+     */
+    value: number;
+};
 /**
  * Allowed value types for WGSL `const` define injection.
  */
@@ -22,15 +31,15 @@ export type MaterialDefineValue = boolean | number | TypedMaterialDefineValue;
 /**
  * Define map keyed by uniform-compatible identifier names.
  */
-export type MaterialDefines = Record<string, MaterialDefineValue>;
+export type MaterialDefines<TKey extends string = string> = Record<TKey, MaterialDefineValue>;
 /**
  * Include map keyed by include identifier used in `#include <name>` directives.
  */
-export type MaterialIncludes = Record<string, string>;
+export type MaterialIncludes<TKey extends string = string> = Record<TKey, string>;
 /**
  * External material input accepted by {@link defineMaterial}.
  */
-export interface FragMaterialInput {
+export interface FragMaterialInput<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string> {
     /**
      * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
      */
@@ -38,24 +47,24 @@ export interface FragMaterialInput {
     /**
      * Initial uniform values.
      */
-    uniforms?: UniformMap;
+    uniforms?: UniformMap<TUniformKey>;
     /**
      * Texture definitions keyed by texture uniform name.
      */
-    textures?: TextureDefinitionMap;
+    textures?: TextureDefinitionMap<TTextureKey>;
     /**
      * Optional compile-time define constants injected into WGSL.
      */
-    defines?: MaterialDefines;
+    defines?: MaterialDefines<TDefineKey>;
     /**
      * Optional WGSL include chunks used by `#include <name>` directives.
      */
-    includes?: MaterialIncludes;
+    includes?: MaterialIncludes<TIncludeKey>;
 }
 /**
  * Normalized and immutable material declaration consumed by `FragCanvas`.
  */
-export interface FragMaterial {
+export interface FragMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string> {
     /**
      * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
      */
@@ -63,24 +72,24 @@ export interface FragMaterial {
     /**
      * Initial uniform values.
      */
-    readonly uniforms: Readonly<UniformMap>;
+    readonly uniforms: Readonly<UniformMap<TUniformKey>>;
     /**
      * Texture definitions keyed by texture uniform name.
      */
-    readonly textures: Readonly<TextureDefinitionMap>;
+    readonly textures: Readonly<TextureDefinitionMap<TTextureKey>>;
     /**
      * Optional compile-time define constants injected into WGSL.
      */
-    readonly defines: Readonly<MaterialDefines>;
+    readonly defines: Readonly<MaterialDefines<TDefineKey>>;
     /**
      * Optional WGSL include chunks used by `#include <name>` directives.
      */
-    readonly includes: Readonly<MaterialIncludes>;
+    readonly includes: Readonly<MaterialIncludes<TIncludeKey>>;
 }
 /**
  * Fully resolved, immutable material snapshot used for renderer creation/caching.
  */
-export interface ResolvedMaterial {
+export interface ResolvedMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TIncludeKey extends string = string> {
     /**
      * Final fragment WGSL after define injection.
      */
@@ -92,11 +101,11 @@ export interface ResolvedMaterial {
     /**
      * Cloned uniforms.
      */
-    uniforms: UniformMap;
+    uniforms: UniformMap<TUniformKey>;
     /**
      * Cloned texture definitions.
      */
-    textures: TextureDefinitionMap;
+    textures: TextureDefinitionMap<TTextureKey>;
     /**
      * Resolved packed uniform layout.
      */
@@ -104,7 +113,7 @@ export interface ResolvedMaterial {
     /**
      * Sorted texture keys.
      */
-    textureKeys: string[];
+    textureKeys: TTextureKey[];
     /**
      * Deterministic JSON signature for cache invalidation.
      */
@@ -116,7 +125,7 @@ export interface ResolvedMaterial {
     /**
      * Normalized include sources map.
      */
-    includeSources: MaterialIncludes;
+    includeSources: MaterialIncludes<TIncludeKey>;
     /**
      * Deterministic define block source used for diagnostics mapping.
      */
@@ -147,11 +156,11 @@ export declare function applyMaterialDefines(fragment: string, defines: Material
  * @param input - User material declaration.
  * @returns Frozen material object safe to share and cache.
  */
-export declare function defineMaterial(input: FragMaterialInput): FragMaterial;
+export declare function defineMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string>(input: FragMaterialInput<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>): FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>;
 /**
  * Resolves a material to renderer-ready data and a deterministic signature.
  *
  * @param material - Material input created via {@link defineMaterial}.
  * @returns Resolved material with packed uniform layout, sorted texture keys and cache signature.
  */
-export declare function resolveMaterial(material: FragMaterial): ResolvedMaterial;
+export declare function resolveMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string>(material: FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey>): ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey>;

package/dist/core/material.js

@@ -6,12 +6,17 @@ import { normalizeDefines, normalizeIncludes, preprocessMaterialFragment, toDefi
  */
 const FRAGMENT_FUNCTION_SIGNATURE_PATTERN = /\bfn\s+frag\s*\(\s*([^)]*?)\s*\)\s*->\s*([A-Za-z_][A-Za-z0-9_<>\s]*)\s*(?:\{|$)/m;
 const FRAGMENT_FUNCTION_NAME_PATTERN = /\bfn\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
-/**
- * Cache of resolved material snapshots keyed by immutable material instance.
- */
 const resolvedMaterialCache = new WeakMap();
 const preprocessedFragmentCache = new WeakMap();
 const materialSourceMetadataCache = new WeakMap();
+function getCachedResolvedMaterial(material) {
+    const cached = resolvedMaterialCache.get(material);
+    if (!cached) {
+        return null;
+    }
+    // Invariant: the cache key is the same material object used to produce this resolved payload.
+    return cached;
+}
 const STACK_TRACE_CHROME_PATTERN = /^\s*at\s+(?:(.*?)\s+\()?(.+?):(\d+):(\d+)\)?$/;
 const STACK_TRACE_FIREFOX_PATTERN = /^(.*?)@(.+?):(\d+):(\d+)$/;
 function getPathBasename(path) {
@@ -204,9 +209,11 @@ function resolveTextures(textures) {
     const resolved = {};
     for (const [name, definition] of Object.entries(textures ?? {})) {
         assertUniformName(name);
+        const source = definition?.source;
+        const normalizedSource = cloneTextureValue(source);
         const clonedDefinition = {
             ...(definition ?? {}),
-            source: cloneTextureValue(definition?.source)
+            ...(source !== undefined ? { source: normalizedSource } : {})
         };
         resolved[name] = Object.freeze(clonedDefinition);
     }
@@ -296,8 +303,8 @@ export function defineMaterial(input) {
     const source = Object.freeze(resolveSourceMetadata(undefined));
     const preprocessed = preprocessMaterialFragment({
         fragment,
-        defines: defines,
-        includes: includes
+        defines,
+        includes
     });
     const material = Object.freeze({
         fragment,
@@ -318,7 +325,7 @@ export function defineMaterial(input) {
  */
 export function resolveMaterial(material) {
     assertDefinedMaterial(material);
-    const cached = resolvedMaterialCache.get(material);
+    const cached = getCachedResolvedMaterial(material);
     if (cached) {
         return cached;
     }

package/dist/core/types.d.ts

@@ -11,7 +11,21 @@ export type UniformType = 'f32' | 'vec2f' | 'vec3f' | 'vec4f' | 'mat4x4f';
  * @typeParam TType - WGSL type tag.
  * @typeParam TValue - Runtime value shape for the selected type.
  */
-export interface TypedUniform<TType extends UniformType = UniformType, TValue = unknown> {
+/**
+ * Accepted matrix value formats for `mat4x4f` uniforms.
+ */
+export type UniformMat4Value = number[] | Float32Array;
+/**
+ * Runtime value shape by WGSL uniform type tag.
+ */
+export interface UniformValueByType {
+    f32: number;
+    vec2f: [number, number];
+    vec3f: [number, number, number];
+    vec4f: [number, number, number, number];
+    mat4x4f: UniformMat4Value;
+}
+export interface TypedUniform<TType extends UniformType = UniformType, TValue extends UniformValueByType[TType] = UniformValueByType[TType]> {
     /**
      * WGSL type tag.
      */
@@ -21,18 +35,14 @@ export interface TypedUniform<TType extends UniformType = UniformType, TValue =
      */
     value: TValue;
 }
-/**
- * Accepted matrix value formats for `mat4x4f` uniforms.
- */
-export type UniformMat4Value = number[] | Float32Array;
 /**
  * Supported uniform input shapes accepted by material and render APIs.
  */
-export type UniformValue = number | [number, number] | [number, number, number] | [number, number, number, number] | TypedUniform<'f32', number> | TypedUniform<'vec2f', [number, number]> | TypedUniform<'vec3f', [number, number, number]> | TypedUniform<'vec4f', [number, number, number, number]> | TypedUniform<'mat4x4f', UniformMat4Value>;
+export type UniformValue = number | [number, number] | [number, number, number] | [number, number, number, number] | TypedUniform<'f32'> | TypedUniform<'vec2f'> | TypedUniform<'vec3f'> | TypedUniform<'vec4f'> | TypedUniform<'mat4x4f'>;
 /**
  * Uniform map keyed by WGSL identifier names.
  */
-export type UniformMap = Record<string, UniformValue>;
+export type UniformMap<TKey extends string = string> = Record<TKey, UniformValue>;
 /**
  * Resolved layout metadata for a single uniform field inside the packed uniform buffer.
  */
@@ -168,11 +178,11 @@ export interface TextureDefinition {
 /**
  * Texture definition map keyed by uniform-compatible texture names.
  */
-export type TextureDefinitionMap = Record<string, TextureDefinition>;
+export type TextureDefinitionMap<TKey extends string = string> = Record<TKey, TextureDefinition>;
 /**
  * Runtime texture value map keyed by texture uniform names.
  */
-export type TextureMap = Record<string, TextureValue>;
+export type TextureMap<TKey extends string = string> = Record<TKey, TextureValue>;
 /**
  * Output color space requested for final canvas presentation.
  */
@@ -226,7 +236,7 @@ export interface RenderTarget {
 /**
  * Named render target definitions keyed by output slot names.
  */
-export type RenderTargetDefinitionMap = Record<string, RenderTargetDefinition>;
+export type RenderTargetDefinitionMap<TKey extends string = string> = Record<TKey, RenderTargetDefinition>;
 /**
  * User-defined render slot name (mapped to `renderTargets` keys).
  */

package/dist/react/FragCanvas.d.ts

@@ -0,0 +1,26 @@
+import { type MotionGPUErrorReport } from '../core/error-report.js';
+import type { FragMaterial } from '../core/material.js';
+import type { OutputColorSpace, RenderPass, RenderMode, RenderTargetDefinitionMap } from '../core/types.js';
+import { type CSSProperties, type ReactNode } from 'react';
+export interface FragCanvasProps {
+    material: FragMaterial;
+    renderTargets?: RenderTargetDefinitionMap;
+    passes?: RenderPass[];
+    clearColor?: [number, number, number, number];
+    outputColorSpace?: OutputColorSpace;
+    renderMode?: RenderMode;
+    autoRender?: boolean;
+    maxDelta?: number;
+    adapterOptions?: GPURequestAdapterOptions;
+    deviceDescriptor?: GPUDeviceDescriptor;
+    dpr?: number;
+    showErrorOverlay?: boolean;
+    errorRenderer?: (report: MotionGPUErrorReport) => ReactNode;
+    onError?: (report: MotionGPUErrorReport) => void;
+    errorHistoryLimit?: number;
+    onErrorHistory?: (history: MotionGPUErrorReport[]) => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+export declare function FragCanvas({ material, renderTargets, passes, clearColor, outputColorSpace, renderMode, autoRender, maxDelta, adapterOptions, deviceDescriptor, dpr, showErrorOverlay, errorRenderer, onError, errorHistoryLimit, onErrorHistory, className, style, children }: FragCanvasProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/FragCanvas.js

@@ -0,0 +1,218 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createCurrentWritable as currentWritable } from '../core/current-value.js';
+import { toMotionGPUErrorReport } from '../core/error-report.js';
+import { createFrameRegistry } from '../core/frame-registry.js';
+import { createMotionGPURuntimeLoop } from '../core/runtime-loop.js';
+import { useEffect, useRef, useState } from 'react';
+import { FrameRegistryReactContext } from './frame-context.js';
+import { MotionGPUErrorOverlay } from './MotionGPUErrorOverlay.js';
+import { MotionGPUReactContext } from './motiongpu-context.js';
+function getInitialDpr() {
+    if (typeof window === 'undefined') {
+        return 1;
+    }
+    return window.devicePixelRatio ?? 1;
+}
+function createRuntimeState(initialDpr) {
+    const registry = createFrameRegistry({ maxDelta: 0.1 });
+    const canvasRef = { current: undefined };
+    const requestFrameSignalRef = { current: null };
+    const requestFrame = () => {
+        requestFrameSignalRef.current?.();
+    };
+    const invalidateFrame = () => {
+        registry.invalidate();
+        requestFrame();
+    };
+    const advanceFrame = () => {
+        registry.advance();
+        requestFrame();
+    };
+    const size = currentWritable({ width: 0, height: 0 });
+    const dprState = currentWritable(initialDpr, requestFrame);
+    const maxDeltaState = currentWritable(0.1, (value) => {
+        registry.setMaxDelta(value);
+        requestFrame();
+    });
+    const renderModeState = currentWritable('always', (value) => {
+        registry.setRenderMode(value);
+        requestFrame();
+    });
+    const autoRenderState = currentWritable(true, (value) => {
+        registry.setAutoRender(value);
+        requestFrame();
+    });
+    const userState = currentWritable({});
+    const context = {
+        get canvas() {
+            return canvasRef.current;
+        },
+        size,
+        dpr: dprState,
+        maxDelta: maxDeltaState,
+        renderMode: renderModeState,
+        autoRender: autoRenderState,
+        user: userState,
+        invalidate: invalidateFrame,
+        advance: advanceFrame,
+        scheduler: {
+            createStage: registry.createStage,
+            getStage: registry.getStage,
+            setDiagnosticsEnabled: registry.setDiagnosticsEnabled,
+            getDiagnosticsEnabled: registry.getDiagnosticsEnabled,
+            getLastRunTimings: registry.getLastRunTimings,
+            getSchedule: registry.getSchedule,
+            setProfilingEnabled: registry.setProfilingEnabled,
+            setProfilingWindow: registry.setProfilingWindow,
+            resetProfiling: registry.resetProfiling,
+            getProfilingEnabled: registry.getProfilingEnabled,
+            getProfilingWindow: registry.getProfilingWindow,
+            getProfilingSnapshot: registry.getProfilingSnapshot
+        }
+    };
+    return {
+        registry,
+        context,
+        canvasRef,
+        size,
+        dprState,
+        maxDeltaState,
+        renderModeState,
+        autoRenderState,
+        requestFrameSignalRef,
+        requestFrame,
+        invalidateFrame,
+        advanceFrame
+    };
+}
+function getNormalizedErrorHistoryLimit(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        return 0;
+    }
+    return Math.floor(value);
+}
+export function FragCanvas({ material, renderTargets = {}, passes = [], clearColor = [0, 0, 0, 1], outputColorSpace = 'srgb', renderMode = 'always', autoRender = true, maxDelta = 0.1, adapterOptions = undefined, deviceDescriptor = undefined, dpr = getInitialDpr(), showErrorOverlay = true, errorRenderer, onError = undefined, errorHistoryLimit = 0, onErrorHistory = undefined, className = '', style, children }) {
+    const runtimeRef = useRef(null);
+    if (!runtimeRef.current) {
+        runtimeRef.current = createRuntimeState(getInitialDpr());
+    }
+    const runtime = runtimeRef.current;
+    const runtimePropsRef = useRef({
+        material,
+        renderTargets,
+        passes,
+        clearColor,
+        outputColorSpace,
+        adapterOptions,
+        deviceDescriptor,
+        onError,
+        errorHistoryLimit,
+        onErrorHistory
+    });
+    runtimePropsRef.current = {
+        material,
+        renderTargets,
+        passes,
+        clearColor,
+        outputColorSpace,
+        adapterOptions,
+        deviceDescriptor,
+        onError,
+        errorHistoryLimit,
+        onErrorHistory
+    };
+    const [errorReport, setErrorReport] = useState(null);
+    const [errorHistory, setErrorHistory] = useState([]);
+    useEffect(() => {
+        runtime.renderModeState.set(renderMode);
+    }, [renderMode, runtime]);
+    useEffect(() => {
+        runtime.autoRenderState.set(autoRender);
+    }, [autoRender, runtime]);
+    useEffect(() => {
+        runtime.maxDeltaState.set(maxDelta);
+    }, [maxDelta, runtime]);
+    useEffect(() => {
+        runtime.dprState.set(dpr);
+    }, [dpr, runtime]);
+    useEffect(() => {
+        const limit = getNormalizedErrorHistoryLimit(errorHistoryLimit);
+        if (limit <= 0) {
+            if (errorHistory.length === 0) {
+                return;
+            }
+            setErrorHistory([]);
+            onErrorHistory?.([]);
+            return;
+        }
+        if (errorHistory.length <= limit) {
+            return;
+        }
+        const trimmed = errorHistory.slice(errorHistory.length - limit);
+        setErrorHistory(trimmed);
+        onErrorHistory?.(trimmed);
+    }, [errorHistory, errorHistoryLimit, onErrorHistory]);
+    useEffect(() => {
+        const canvas = runtime.canvasRef.current;
+        if (!canvas) {
+            const report = toMotionGPUErrorReport(new Error('Canvas element is not available'), 'initialization');
+            setErrorReport(report);
+            const historyLimit = getNormalizedErrorHistoryLimit(runtimePropsRef.current.errorHistoryLimit);
+            if (historyLimit > 0) {
+                const nextHistory = [report].slice(-historyLimit);
+                setErrorHistory(nextHistory);
+                runtimePropsRef.current.onErrorHistory?.(nextHistory);
+            }
+            runtimePropsRef.current.onError?.(report);
+            return () => {
+                runtime.registry.clear();
+            };
+        }
+        const runtimeLoop = createMotionGPURuntimeLoop({
+            canvas,
+            registry: runtime.registry,
+            size: runtime.size,
+            dpr: runtime.dprState,
+            maxDelta: runtime.maxDeltaState,
+            getMaterial: () => runtimePropsRef.current.material,
+            getRenderTargets: () => runtimePropsRef.current.renderTargets,
+            getPasses: () => runtimePropsRef.current.passes,
+            getClearColor: () => runtimePropsRef.current.clearColor,
+            getOutputColorSpace: () => runtimePropsRef.current.outputColorSpace,
+            getAdapterOptions: () => runtimePropsRef.current.adapterOptions,
+            getDeviceDescriptor: () => runtimePropsRef.current.deviceDescriptor,
+            getOnError: () => runtimePropsRef.current.onError,
+            getErrorHistoryLimit: () => runtimePropsRef.current.errorHistoryLimit,
+            getOnErrorHistory: () => runtimePropsRef.current.onErrorHistory,
+            reportErrorHistory: (history) => {
+                setErrorHistory(history);
+            },
+            reportError: (report) => {
+                setErrorReport(report);
+            }
+        });
+        runtime.requestFrameSignalRef.current = runtimeLoop.requestFrame;
+        return () => {
+            runtime.requestFrameSignalRef.current = null;
+            runtimeLoop.destroy();
+        };
+    }, [runtime]);
+    const canvasStyle = {
+        position: 'absolute',
+        inset: 0,
+        display: 'block',
+        width: '100%',
+        height: '100%',
+        ...style
+    };
+    return (_jsx(FrameRegistryReactContext.Provider, { value: runtime.registry, children: _jsx(MotionGPUReactContext.Provider, { value: runtime.context, children: _jsxs("div", { className: "motiongpu-canvas-wrap", style: {
+                    position: 'relative',
+                    width: '100%',
+                    height: '100%',
+                    minWidth: 0,
+                    minHeight: 0,
+                    overflow: 'hidden'
+                }, children: [_jsx("canvas", { className: className, style: canvasStyle, ref: (node) => {
+                            runtime.canvasRef.current = node ?? undefined;
+                        } }), showErrorOverlay && errorReport ? (errorRenderer ? (errorRenderer(errorReport)) : (_jsx(MotionGPUErrorOverlay, { report: errorReport }))) : null, children] }) }) }));
+}