@motion-core/motion-gpu 0.4.1 → 0.5.0

package/src/lib/react/frame-context.ts

@@ -0,0 +1,169 @@
+import { createContext, useContext, useEffect, useRef } from 'react';
+import { createCurrentWritable } from '../core/current-value.js';
+import { useMotionGPU } from './motiongpu-context.js';
+import type {
+	FrameCallback,
+	FrameKey,
+	FrameProfilingSnapshot,
+	FrameRegistry,
+	FrameRunTimings,
+	FrameScheduleSnapshot,
+	FrameStage,
+	FrameStageCallback,
+	FrameTask,
+	FrameTaskInvalidation,
+	FrameTaskInvalidationToken,
+	UseFrameOptions,
+	UseFrameResult
+} from '../core/frame-registry.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<FrameRegistry | null>(null);
+
+export type {
+	FrameCallback,
+	FrameKey,
+	FrameProfilingSnapshot,
+	FrameRegistry,
+	FrameRunTimings,
+	FrameScheduleSnapshot,
+	FrameStage,
+	FrameStageCallback,
+	FrameTask,
+	FrameTaskInvalidation,
+	FrameTaskInvalidationToken,
+	UseFrameOptions,
+	UseFrameResult
+};
+
+/**
+ * Registers a frame callback using an auto-generated task key.
+ */
+export function useFrame(callback: FrameCallback, options?: UseFrameOptions): UseFrameResult;
+
+/**
+ * Registers a frame callback with an explicit task key.
+ */
+export function useFrame(
+	key: FrameKey,
+	callback: FrameCallback,
+	options?: UseFrameOptions
+): UseFrameResult;
+
+/**
+ * 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: FrameKey | FrameCallback,
+	callbackOrOptions?: FrameCallback | UseFrameOptions,
+	maybeOptions?: UseFrameOptions
+): UseFrameResult {
+	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 as UseFrameOptions | undefined
+				}
+			: {
+					key: keyOrCallback,
+					callback: callbackOrOptions as FrameCallback,
+					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<{
+		key: FrameKey | undefined;
+		options: UseFrameOptions | undefined;
+	} | null>(null);
+	if (!registrationConfigRef.current) {
+		registrationConfigRef.current = {
+			key: resolved.key,
+			options: resolved.options
+		};
+	}
+	const registrationConfig = registrationConfigRef.current;
+
+	const registrationRef = useRef<{
+		task: FrameTask;
+		start: () => void;
+		stop: () => void;
+		started: UseFrameResult['started'];
+		unsubscribe: () => void;
+	} | null>(null);
+	const taskRef = useRef<FrameTask>({
+		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: FrameCallback = (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/src/lib/react/index.ts

@@ -0,0 +1,68 @@
+/**
+ * React adapter entrypoint for MotionGPU.
+ */
+export { FragCanvas } from './FragCanvas.js';
+export { defineMaterial } from '../core/material.js';
+export {
+	BlitPass,
+	CopyPass,
+	ShaderPass,
+	ComputePass,
+	PingPongComputePass
+} 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,
+	AnyPass,
+	ComputePassLike,
+	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';
+export type {
+	StorageBufferAccess,
+	StorageBufferDefinition,
+	StorageBufferDefinitionMap,
+	StorageBufferType,
+	ComputePassContext
+} from '../core/types.js';
+export type { ComputePassOptions, ComputeDispatchContext } from '../passes/ComputePass.js';
+export type { PingPongComputePassOptions } from '../passes/PingPongComputePass.js';

package/src/lib/react/motiongpu-context.ts

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

package/src/lib/react/use-motiongpu-user-context.ts

@@ -0,0 +1,186 @@
+import { useCallback, useMemo } from 'react';
+import type { CurrentReadable } from '../core/current-value.js';
+import {
+	useMotionGPU,
+	type MotionGPUUserContext,
+	type MotionGPUUserNamespace
+} from './motiongpu-context.js';
+
+/**
+ * Internal shape of the user context store.
+ */
+type UserContextStore = Record<MotionGPUUserNamespace, unknown>;
+
+/**
+ * Object-like context payload used by merge semantics.
+ */
+type UserContextEntry = Record<string, 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';
+}
+
+/**
+ * Checks whether a value is a non-array object suitable for shallow merge.
+ */
+function isObjectEntry(value: unknown): value is UserContextEntry {
+	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<UCT = unknown>(
+	userStore: MotionGPUUserContext,
+	namespace: MotionGPUUserNamespace,
+	value: UCT | (() => UCT),
+	options?: SetMotionGPUUserContextOptions
+): UCT | undefined {
+	const mode = options?.existing ?? 'skip';
+	const functionValueMode = options?.functionValue ?? 'factory';
+	let resolvedValue: UCT | undefined;
+
+	userStore.update((context) => {
+		const hasExisting = namespace in context;
+		if (hasExisting && mode === 'skip') {
+			resolvedValue = context[namespace] as UCT | undefined;
+			return context;
+		}
+
+		const nextValue =
+			typeof value === 'function' && functionValueMode === 'factory'
+				? (value as () => UCT)()
+				: (value as UCT);
+		if (hasExisting && mode === 'merge') {
+			const currentValue = context[namespace];
+			if (isObjectEntry(currentValue) && isObjectEntry(nextValue)) {
+				resolvedValue = {
+					...currentValue,
+					...nextValue
+				} as UCT;
+				return {
+					...context,
+					[namespace]: resolvedValue
+				};
+			}
+		}
+
+		resolvedValue = nextValue;
+		return {
+			...context,
+			[namespace]: nextValue
+		};
+	});
+
+	return resolvedValue;
+}
+
+/**
+ * Returns a read-only view of the entire motiongpu user context store.
+ */
+export function useMotionGPUUserContext<
+	UC extends UserContextStore = UserContextStore
+>(): CurrentReadable<UC>;
+
+/**
+ * Reads a namespaced user context value as a reactive readable store.
+ */
+export function useMotionGPUUserContext<
+	UC extends UserContextStore = UserContextStore,
+	K extends keyof UC & MotionGPUUserNamespace = keyof UC & MotionGPUUserNamespace
+>(namespace: K): CurrentReadable<UC[K] | undefined>;
+
+/**
+ * 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<
+	UC extends UserContextStore = UserContextStore,
+	K extends keyof UC & MotionGPUUserNamespace = keyof UC & MotionGPUUserNamespace
+>(namespace?: K): CurrentReadable<UC> | CurrentReadable<UC[K] | undefined> {
+	const userStore = useMotionGPU().user;
+	const allStore = useMemo<CurrentReadable<UC>>(
+		() => ({
+			get current() {
+				return userStore.current as UC;
+			},
+			subscribe(run) {
+				return userStore.subscribe((context) => run(context as UC));
+			}
+		}),
+		[userStore]
+	);
+	const scopedStore = useMemo<CurrentReadable<UC[K] | undefined>>(
+		() => ({
+			get current() {
+				return userStore.current[namespace as MotionGPUUserNamespace] as UC[K] | undefined;
+			},
+			subscribe(run) {
+				return userStore.subscribe((context) =>
+					run(context[namespace as MotionGPUUserNamespace] as UC[K] | undefined)
+				);
+			}
+		}),
+		[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(
+		<UCT = unknown>(
+			namespace: MotionGPUUserNamespace,
+			value: UCT | (() => UCT),
+			options?: SetMotionGPUUserContextOptions
+		): UCT | undefined => 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<UCT = unknown>(
+	namespace: MotionGPUUserNamespace,
+	value: UCT | (() => UCT),
+	options?: SetMotionGPUUserContextOptions
+): UCT | undefined {
+	return setMotionGPUUserContextInStore(useMotionGPU().user, namespace, value, options);
+}