@motion-core/motion-gpu 0.3.0 → 0.4.1

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/render-targets.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="@webgpu/types" />
 import type { RenderTargetDefinitionMap } from './types.js';
 /**
  * Concrete render target configuration resolved for current canvas size.

package/dist/core/runtime-loop.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="@webgpu/types" />
 import type { CurrentReadable, CurrentWritable } from './current-value.js';
 import { type FragMaterial } from './material.js';
 import { type MotionGPUErrorReport } from './error-report.js';

package/dist/core/textures.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="@webgpu/types" />
 import type { TextureData, TextureDefinition, TextureDefinitionMap, TextureUpdateMode, TextureValue } from './types.js';
 /**
  * Texture definition with defaults and normalized numeric limits applied.

package/dist/core/types.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="@webgpu/types" />
 /**
  * Core runtime and API contracts used by MotionGPU's renderer, hooks and scheduler.
  */
@@ -11,7 +12,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 +36,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 +179,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 +237,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/passes/CopyPass.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="@webgpu/types" />
 import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types.js';
 export interface CopyPassOptions extends RenderPassFlags {
     enabled?: boolean;

package/dist/passes/FullscreenPass.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="@webgpu/types" />
 import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types.js';
 export interface FullscreenPassOptions extends RenderPassFlags {
     enabled?: boolean;

package/dist/react/FragCanvas.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="@webgpu/types" />
+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;