@motion-core/motion-gpu 0.3.0 → 0.4.1

package/dist/react/frame-context.js

@@ -0,0 +1,98 @@
+import { createContext, useContext, useEffect, useRef } from 'react';
+import { createCurrentWritable } from '../core/current-value.js';
+import { useMotionGPU } from './motiongpu-context.js';
+/**
+ * Placeholder stage used before a frame task registration becomes available.
+ */
+const PENDING_STAGE_KEY = Symbol('motiongpu-react-pending-stage');
+/**
+ * React context container for the active frame registry.
+ */
+export const FrameRegistryReactContext = createContext(null);
+/**
+ * Registers a callback in the active frame registry and auto-unsubscribes on unmount.
+ *
+ * @param keyOrCallback - Task key or callback for auto-key registration.
+ * @param callbackOrOptions - Callback (keyed overload) or options (auto-key overload).
+ * @param maybeOptions - Optional registration options for keyed overload.
+ * Registration key/options are frozen on first render; subsequent renders do not re-register.
+ * @returns Registration control API with task, start/stop controls and started state.
+ * @throws {Error} When called outside `<FragCanvas>`.
+ * @throws {Error} When callback is missing in keyed overload.
+ */
+export function useFrame(keyOrCallback, callbackOrOptions, maybeOptions) {
+    const registry = useContext(FrameRegistryReactContext);
+    if (!registry) {
+        throw new Error('useFrame must be used inside <FragCanvas>');
+    }
+    const motiongpu = useMotionGPU();
+    const resolved = typeof keyOrCallback === 'function'
+        ? {
+            key: undefined,
+            callback: keyOrCallback,
+            options: callbackOrOptions
+        }
+        : {
+            key: keyOrCallback,
+            callback: callbackOrOptions,
+            options: maybeOptions
+        };
+    if (typeof resolved.callback !== 'function') {
+        throw new Error('useFrame requires a callback');
+    }
+    const callbackRef = useRef(resolved.callback);
+    callbackRef.current = resolved.callback;
+    const registrationConfigRef = useRef(null);
+    if (!registrationConfigRef.current) {
+        registrationConfigRef.current = {
+            key: resolved.key,
+            options: resolved.options
+        };
+    }
+    const registrationConfig = registrationConfigRef.current;
+    const registrationRef = useRef(null);
+    const taskRef = useRef({
+        key: registrationConfig.key !== undefined
+            ? registrationConfig.key
+            : Symbol('motiongpu-react-pending-task-key'),
+        stage: PENDING_STAGE_KEY
+    });
+    const startedStoreRef = useRef(createCurrentWritable(false));
+    const startedStore = startedStoreRef.current;
+    useEffect(() => {
+        const wrappedCallback = (state) => {
+            callbackRef.current(state);
+        };
+        const registration = registrationConfig.key === undefined
+            ? registry.register(wrappedCallback, registrationConfig.options)
+            : registry.register(registrationConfig.key, wrappedCallback, registrationConfig.options);
+        registrationRef.current = registration;
+        taskRef.current = registration.task;
+        const unsubscribeStarted = registration.started.subscribe((value) => {
+            startedStore.set(value);
+        });
+        return () => {
+            unsubscribeStarted();
+            registration.unsubscribe();
+            if (registrationRef.current === registration) {
+                registrationRef.current = null;
+            }
+            startedStore.set(false);
+        };
+    }, [registrationConfig, registry, startedStore]);
+    useEffect(() => {
+        motiongpu.invalidate();
+    }, [motiongpu, resolved.callback]);
+    return {
+        get task() {
+            return taskRef.current;
+        },
+        start: () => {
+            registrationRef.current?.start();
+        },
+        stop: () => {
+            registrationRef.current?.stop();
+        },
+        started: startedStore
+    };
+}

package/dist/react/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * React adapter entrypoint for MotionGPU.
+ */
+export { FragCanvas } from './FragCanvas.js';
+export { defineMaterial } from '../core/material.js';
+export { BlitPass, CopyPass, ShaderPass } from '../passes/index.js';
+export { useMotionGPU } from './motiongpu-context.js';
+export { useFrame } from './frame-context.js';
+export { useTexture } from './use-texture.js';
+export type { FrameInvalidationToken, FrameState, OutputColorSpace, RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot, RenderMode, RenderTarget, RenderTargetDefinition, RenderTargetDefinitionMap, TextureData, TextureDefinition, TextureDefinitionMap, TextureUpdateMode, TextureMap, TextureSource, TextureValue, TypedUniform, UniformMat4Value, UniformMap, UniformType, UniformValue } from '../core/types.js';
+export type { LoadedTexture, TextureDecodeOptions, TextureLoadOptions } from '../core/texture-loader.js';
+export type { FragMaterial, FragMaterialInput, MaterialIncludes, MaterialDefineValue, MaterialDefines, TypedMaterialDefineValue } from '../core/material.js';
+export type { MotionGPUContext } from './motiongpu-context.js';
+export type { UseFrameOptions, UseFrameResult } from './frame-context.js';
+export type { TextureUrlInput, UseTextureResult } from './use-texture.js';

package/dist/react/index.js

@@ -0,0 +1,9 @@
+/**
+ * React adapter entrypoint for MotionGPU.
+ */
+export { FragCanvas } from './FragCanvas.js';
+export { defineMaterial } from '../core/material.js';
+export { BlitPass, CopyPass, ShaderPass } from '../passes/index.js';
+export { useMotionGPU } from './motiongpu-context.js';
+export { useFrame } from './frame-context.js';
+export { useTexture } from './use-texture.js';

package/dist/react/motiongpu-context.d.ts

@@ -0,0 +1,73 @@
+import type { RenderMode } from '../core/types.js';
+import type { CurrentReadable, CurrentWritable } from '../core/current-value.js';
+import type { FrameProfilingSnapshot, FrameRunTimings, FrameScheduleSnapshot } from '../core/frame-registry.js';
+import type { MotionGPUScheduler as CoreMotionGPUScheduler } from '../core/scheduler-helpers.js';
+/**
+ * React context payload exposed by `<FragCanvas>`.
+ */
+export interface MotionGPUContext {
+    /**
+     * Underlying canvas element used by the renderer.
+     */
+    canvas: HTMLCanvasElement | undefined;
+    /**
+     * Reactive canvas pixel size.
+     */
+    size: CurrentReadable<{
+        width: number;
+        height: number;
+    }>;
+    /**
+     * Device pixel ratio multiplier.
+     */
+    dpr: CurrentWritable<number>;
+    /**
+     * Max frame delta clamp passed to scheduled callbacks.
+     */
+    maxDelta: CurrentWritable<number>;
+    /**
+     * Scheduler render mode (`always`, `on-demand`, `manual`).
+     */
+    renderMode: CurrentWritable<RenderMode>;
+    /**
+     * Global toggle for automatic rendering.
+     */
+    autoRender: CurrentWritable<boolean>;
+    /**
+     * Namespaced user context store shared within the canvas subtree.
+     */
+    user: MotionGPUUserContext;
+    /**
+     * Marks current frame as invalidated.
+     */
+    invalidate: () => void;
+    /**
+     * Requests one manual frame advance.
+     */
+    advance: () => void;
+    /**
+     * Public scheduler API.
+     */
+    scheduler: MotionGPUScheduler;
+}
+export type MotionGPUScheduler = CoreMotionGPUScheduler;
+export type { FrameProfilingSnapshot, FrameRunTimings, FrameScheduleSnapshot };
+/**
+ * Namespace identifier for user-owned context entries.
+ */
+export type MotionGPUUserNamespace = string | symbol;
+/**
+ * Shared user context store exposed by `FragCanvas`.
+ */
+export type MotionGPUUserContext = CurrentWritable<Record<MotionGPUUserNamespace, unknown>>;
+/**
+ * Internal React context container.
+ */
+export declare const MotionGPUReactContext: import("react").Context<MotionGPUContext | null>;
+/**
+ * Returns active MotionGPU runtime context.
+ *
+ * @returns Active context.
+ * @throws {Error} When called outside `<FragCanvas>`.
+ */
+export declare function useMotionGPU(): MotionGPUContext;

package/dist/react/motiongpu-context.js

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react';
+/**
+ * Internal React context container.
+ */
+export const MotionGPUReactContext = createContext(null);
+/**
+ * Returns active MotionGPU runtime context.
+ *
+ * @returns Active context.
+ * @throws {Error} When called outside `<FragCanvas>`.
+ */
+export function useMotionGPU() {
+    const context = useContext(MotionGPUReactContext);
+    if (!context) {
+        throw new Error('useMotionGPU must be used inside <FragCanvas>');
+    }
+    return context;
+}

package/dist/react/use-motiongpu-user-context.d.ts

@@ -0,0 +1,49 @@
+import type { CurrentReadable } from '../core/current-value.js';
+import { type MotionGPUUserNamespace } from './motiongpu-context.js';
+/**
+ * Internal shape of the user context store.
+ */
+type UserContextStore = Record<MotionGPUUserNamespace, unknown>;
+/**
+ * Controls how a namespaced user context value behaves when already present.
+ */
+export interface SetMotionGPUUserContextOptions {
+    /**
+     * Conflict strategy when namespace already exists:
+     * - `skip`: keep current value
+     * - `replace`: replace current value
+     * - `merge`: shallow merge object values, fallback to replace otherwise
+     *
+     * @default 'skip'
+     */
+    existing?: 'merge' | 'replace' | 'skip';
+    /**
+     * How function inputs should be interpreted:
+     * - `factory`: call function and store its return value
+     * - `value`: store function itself
+     *
+     * @default 'factory'
+     */
+    functionValue?: 'factory' | 'value';
+}
+/**
+ * Returns a read-only view of the entire motiongpu user context store.
+ */
+export declare function useMotionGPUUserContext<UC extends UserContextStore = UserContextStore>(): CurrentReadable<UC>;
+/**
+ * Reads a namespaced user context value as a reactive readable store.
+ */
+export declare function useMotionGPUUserContext<UC extends UserContextStore = UserContextStore, K extends keyof UC & MotionGPUUserNamespace = keyof UC & MotionGPUUserNamespace>(namespace: K): CurrentReadable<UC[K] | undefined>;
+/**
+ * Returns a stable setter bound to the active MotionGPU user context store.
+ *
+ * @returns Setter function that preserves namespace write semantics.
+ */
+export declare function useSetMotionGPUUserContext(): <UCT = unknown>(namespace: MotionGPUUserNamespace, value: UCT | (() => UCT), options?: SetMotionGPUUserContextOptions) => UCT | undefined;
+/**
+ * Sets a namespaced user context value with explicit write semantics.
+ *
+ * Returns the effective value stored under the namespace.
+ */
+export declare function setMotionGPUUserContext<UCT = unknown>(namespace: MotionGPUUserNamespace, value: UCT | (() => UCT), options?: SetMotionGPUUserContextOptions): UCT | undefined;
+export {};

package/dist/react/use-motiongpu-user-context.js

@@ -0,0 +1,94 @@
+import { useCallback, useMemo } from 'react';
+import { useMotionGPU } from './motiongpu-context.js';
+/**
+ * Checks whether a value is a non-array object suitable for shallow merge.
+ */
+function isObjectEntry(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Sets a namespaced user context value in the provided user store.
+ *
+ * Returns the effective value stored under the namespace.
+ */
+function setMotionGPUUserContextInStore(userStore, namespace, value, options) {
+    const mode = options?.existing ?? 'skip';
+    const functionValueMode = options?.functionValue ?? 'factory';
+    let resolvedValue;
+    userStore.update((context) => {
+        const hasExisting = namespace in context;
+        if (hasExisting && mode === 'skip') {
+            resolvedValue = context[namespace];
+            return context;
+        }
+        const nextValue = typeof value === 'function' && functionValueMode === 'factory'
+            ? value()
+            : value;
+        if (hasExisting && mode === 'merge') {
+            const currentValue = context[namespace];
+            if (isObjectEntry(currentValue) && isObjectEntry(nextValue)) {
+                resolvedValue = {
+                    ...currentValue,
+                    ...nextValue
+                };
+                return {
+                    ...context,
+                    [namespace]: resolvedValue
+                };
+            }
+        }
+        resolvedValue = nextValue;
+        return {
+            ...context,
+            [namespace]: nextValue
+        };
+    });
+    return resolvedValue;
+}
+/**
+ * Read-only user context hook:
+ * - no args: returns full user context store
+ * - namespace: returns namespaced store view
+ *
+ * @param namespace - Optional namespace key.
+ */
+export function useMotionGPUUserContext(namespace) {
+    const userStore = useMotionGPU().user;
+    const allStore = useMemo(() => ({
+        get current() {
+            return userStore.current;
+        },
+        subscribe(run) {
+            return userStore.subscribe((context) => run(context));
+        }
+    }), [userStore]);
+    const scopedStore = useMemo(() => ({
+        get current() {
+            return userStore.current[namespace];
+        },
+        subscribe(run) {
+            return userStore.subscribe((context) => run(context[namespace]));
+        }
+    }), [namespace, userStore]);
+    if (namespace === undefined) {
+        return allStore;
+    }
+    return scopedStore;
+}
+/**
+ * Returns a stable setter bound to the active MotionGPU user context store.
+ *
+ * @returns Setter function that preserves namespace write semantics.
+ */
+export function useSetMotionGPUUserContext() {
+    const userStore = useMotionGPU().user;
+    return useCallback((namespace, value, options) => setMotionGPUUserContextInStore(userStore, namespace, value, options), [userStore]);
+}
+/**
+ * Sets a namespaced user context value with explicit write semantics.
+ *
+ * Returns the effective value stored under the namespace.
+ */
+export function setMotionGPUUserContext(namespace, value, options) {
+    return setMotionGPUUserContextInStore(useMotionGPU().user, namespace, value, options);
+}

package/dist/react/use-texture.d.ts

@@ -0,0 +1,40 @@
+import { type CurrentReadable } from '../core/current-value.js';
+import { type LoadedTexture, type TextureLoadOptions } from '../core/texture-loader.js';
+import { type MotionGPUErrorReport } from '../core/error-report.js';
+/**
+ * Reactive state returned by `useTexture`.
+ */
+export interface UseTextureResult {
+    /**
+     * Loaded textures or `null` when unavailable/failed.
+     */
+    textures: CurrentReadable<LoadedTexture[] | null>;
+    /**
+     * `true` while an active load request is running.
+     */
+    loading: CurrentReadable<boolean>;
+    /**
+     * Last loading error.
+     */
+    error: CurrentReadable<Error | null>;
+    /**
+     * Last loading error normalized to MotionGPU diagnostics report shape.
+     */
+    errorReport: CurrentReadable<MotionGPUErrorReport | null>;
+    /**
+     * Reloads all textures using current URL input.
+     */
+    reload: () => Promise<void>;
+}
+/**
+ * Supported URL input variants for `useTexture`.
+ */
+export type TextureUrlInput = string[] | (() => string[]);
+/**
+ * Loads textures from URLs and exposes reactive loading/error state.
+ *
+ * @param urlInput - URLs array or lazy URL provider.
+ * @param options - Loader options passed to URL fetch/decode pipeline.
+ * @returns Reactive texture loading state with reload support.
+ */
+export declare function useTexture(urlInput: TextureUrlInput, options?: TextureLoadOptions): UseTextureResult;

package/dist/react/use-texture.js

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { createCurrentWritable as currentWritable } from '../core/current-value.js';
+import { isAbortError, loadTexturesFromUrls } from '../core/texture-loader.js';
+import { toMotionGPUErrorReport } from '../core/error-report.js';
+/**
+ * Normalizes unknown thrown values to an `Error` instance.
+ */
+function toError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error('Unknown texture loading error');
+}
+/**
+ * Releases GPU-side resources for a list of loaded textures.
+ */
+function disposeTextures(list) {
+    for (const texture of list ?? []) {
+        texture.dispose();
+    }
+}
+function mergeAbortSignals(primary, secondary) {
+    if (!secondary) {
+        return {
+            signal: primary,
+            dispose: () => { }
+        };
+    }
+    if (typeof AbortSignal.any === 'function') {
+        return {
+            signal: AbortSignal.any([primary, secondary]),
+            dispose: () => { }
+        };
+    }
+    const fallback = new AbortController();
+    let disposed = false;
+    const cleanup = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        primary.removeEventListener('abort', abort);
+        secondary.removeEventListener('abort', abort);
+    };
+    const abort = () => fallback.abort();
+    primary.addEventListener('abort', abort, { once: true });
+    secondary.addEventListener('abort', abort, { once: true });
+    return {
+        signal: fallback.signal,
+        dispose: cleanup
+    };
+}
+/**
+ * Loads textures from URLs and exposes reactive loading/error state.
+ *
+ * @param urlInput - URLs array or lazy URL provider.
+ * @param options - Loader options passed to URL fetch/decode pipeline.
+ * @returns Reactive texture loading state with reload support.
+ */
+export function useTexture(urlInput, options = {}) {
+    const texturesRef = useRef(currentWritable(null));
+    const loadingRef = useRef(currentWritable(true));
+    const errorRef = useRef(currentWritable(null));
+    const errorReportRef = useRef(currentWritable(null));
+    const activeControllerRef = useRef(null);
+    const runningLoadRef = useRef(null);
+    const reloadQueuedRef = useRef(false);
+    const requestVersionRef = useRef(0);
+    const disposedRef = useRef(false);
+    const optionsRef = useRef(options);
+    const urlInputRef = useRef(urlInput);
+    optionsRef.current = options;
+    urlInputRef.current = urlInput;
+    const getUrls = useCallback(() => {
+        const currentInput = urlInputRef.current;
+        return typeof currentInput === 'function' ? currentInput() : currentInput;
+    }, []);
+    const executeLoad = useCallback(async () => {
+        if (disposedRef.current) {
+            return;
+        }
+        const version = ++requestVersionRef.current;
+        const controller = new AbortController();
+        activeControllerRef.current = controller;
+        loadingRef.current.set(true);
+        errorRef.current.set(null);
+        errorReportRef.current.set(null);
+        const previous = texturesRef.current.current;
+        const mergedSignal = mergeAbortSignals(controller.signal, optionsRef.current.signal);
+        try {
+            const loaded = await loadTexturesFromUrls(getUrls(), {
+                ...optionsRef.current,
+                signal: mergedSignal.signal
+            });
+            if (disposedRef.current || version !== requestVersionRef.current) {
+                disposeTextures(loaded);
+                return;
+            }
+            texturesRef.current.set(loaded);
+            disposeTextures(previous);
+        }
+        catch (nextError) {
+            if (disposedRef.current || version !== requestVersionRef.current) {
+                return;
+            }
+            if (isAbortError(nextError)) {
+                return;
+            }
+            disposeTextures(previous);
+            texturesRef.current.set(null);
+            const normalizedError = toError(nextError);
+            errorRef.current.set(normalizedError);
+            errorReportRef.current.set(toMotionGPUErrorReport(normalizedError, 'initialization'));
+        }
+        finally {
+            if (!disposedRef.current && version === requestVersionRef.current) {
+                loadingRef.current.set(false);
+            }
+            if (activeControllerRef.current === controller) {
+                activeControllerRef.current = null;
+            }
+            mergedSignal.dispose();
+        }
+    }, [getUrls]);
+    const runLoadLoop = useCallback(async () => {
+        do {
+            reloadQueuedRef.current = false;
+            await executeLoad();
+        } while (reloadQueuedRef.current && !disposedRef.current);
+    }, [executeLoad]);
+    const load = useCallback(() => {
+        activeControllerRef.current?.abort();
+        if (runningLoadRef.current) {
+            reloadQueuedRef.current = true;
+            return runningLoadRef.current;
+        }
+        const pending = runLoadLoop();
+        const trackedPending = pending.finally(() => {
+            if (runningLoadRef.current === trackedPending) {
+                runningLoadRef.current = null;
+            }
+        });
+        runningLoadRef.current = trackedPending;
+        return trackedPending;
+    }, [runLoadLoop]);
+    useEffect(() => {
+        void load();
+        return () => {
+            disposedRef.current = true;
+            requestVersionRef.current += 1;
+            activeControllerRef.current?.abort();
+            disposeTextures(texturesRef.current.current);
+        };
+    }, [load]);
+    return {
+        textures: texturesRef.current,
+        loading: loadingRef.current,
+        error: errorRef.current,
+        errorReport: errorReportRef.current,
+        reload: load
+    };
+}

package/dist/svelte/FragCanvas.svelte

@@ -66,20 +66,18 @@
 	let errorReport = $state<MotionGPUErrorReport | null>(null);
 	let errorHistory = $state<MotionGPUErrorReport[]>([]);
 
-	const getNormalizedErrorHistoryLimit = (): number => {
+	let normalizedErrorHistoryLimit = $derived.by(() => {
 		if (!Number.isFinite(errorHistoryLimit) || errorHistoryLimit <= 0) {
 			return 0;
 		}
 		return Math.floor(errorHistoryLimit);
-	};
+	});
 
 	const bindCanvas = (node: HTMLCanvasElement) => {
 		canvas = node;
-		return {
-			destroy: () => {
-				if (canvas === node) {
-					canvas = undefined;
-				}
+		return () => {
+			if (canvas === node) {
+				canvas = undefined;
 			}
 		};
 	};
@@ -144,26 +142,14 @@
 
 	$effect(() => {
 		renderModeState.set(renderMode);
-		requestFrame();
-	});
-
-	$effect(() => {
 		autoRenderState.set(autoRender);
-		requestFrame();
-	});
-
-	$effect(() => {
 		maxDeltaState.set(maxDelta);
-		requestFrame();
-	});
-
-	$effect(() => {
 		dprState.set(dpr);
 		requestFrame();
 	});
 
 	$effect(() => {
-		const limit = getNormalizedErrorHistoryLimit();
+		const limit = normalizedErrorHistoryLimit;
 		if (limit <= 0) {
 			if (errorHistory.length === 0) {
 				return;
@@ -189,7 +175,7 @@
 				'initialization'
 			);
 			errorReport = report;
-			const historyLimit = getNormalizedErrorHistoryLimit();
+			const historyLimit = normalizedErrorHistoryLimit;
 			if (historyLimit > 0) {
 				const nextHistory = [report].slice(-historyLimit);
 				errorHistory = nextHistory;
@@ -232,7 +218,7 @@
 </script>
 
 <div class="motiongpu-canvas-wrap">
-	<canvas use:bindCanvas class={className} {style}></canvas>
+	<canvas {@attach bindCanvas} class={className} {style}></canvas>
 	{#if showErrorOverlay && errorReport}
 		{#if errorRenderer}
 			{@render errorRenderer(errorReport)}

package/dist/svelte/FragCanvas.svelte.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="@webgpu/types" />
 import type { Snippet } from 'svelte';
 import type { FragMaterial } from '../core/material';
 import { type MotionGPUErrorReport } from '../core/error-report';