@motion-core/motion-gpu 0.4.0 → 0.4.2

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);
+}

package/src/lib/react/use-texture.ts

@@ -0,0 +1,233 @@
+import { useCallback, useEffect, useRef } from 'react';
+import {
+	createCurrentWritable as currentWritable,
+	type CurrentReadable
+} from '../core/current-value.js';
+import {
+	isAbortError,
+	loadTexturesFromUrls,
+	type LoadedTexture,
+	type TextureLoadOptions
+} from '../core/texture-loader.js';
+import { toMotionGPUErrorReport, 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[]);
+
+/**
+ * Normalizes unknown thrown values to an `Error` instance.
+ */
+function toError(error: unknown): 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: LoadedTexture[] | null): void {
+	for (const texture of list ?? []) {
+		texture.dispose();
+	}
+}
+
+interface MergedAbortSignal {
+	signal: AbortSignal;
+	dispose: () => void;
+}
+
+function mergeAbortSignals(
+	primary: AbortSignal,
+	secondary: AbortSignal | undefined
+): MergedAbortSignal {
+	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 = (): void => {
+		if (disposed) {
+			return;
+		}
+		disposed = true;
+		primary.removeEventListener('abort', abort);
+		secondary.removeEventListener('abort', abort);
+	};
+	const abort = (): void => 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: TextureUrlInput,
+	options: TextureLoadOptions = {}
+): UseTextureResult {
+	const texturesRef = useRef(currentWritable<LoadedTexture[] | null>(null));
+	const loadingRef = useRef(currentWritable(true));
+	const errorRef = useRef(currentWritable<Error | null>(null));
+	const errorReportRef = useRef(currentWritable<MotionGPUErrorReport | null>(null));
+	const activeControllerRef = useRef<AbortController | null>(null);
+	const runningLoadRef = useRef<Promise<void> | null>(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((): string[] => {
+		const currentInput = urlInputRef.current;
+		return typeof currentInput === 'function' ? currentInput() : currentInput;
+	}, []);
+
+	const executeLoad = useCallback(async (): Promise<void> => {
+		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 (): Promise<void> => {
+		do {
+			reloadQueuedRef.current = false;
+			await executeLoad();
+		} while (reloadQueuedRef.current && !disposedRef.current);
+	}, [executeLoad]);
+
+	const load = useCallback((): Promise<void> => {
+		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
+	};
+}