@motion-core/motion-gpu 0.4.0 → 0.4.2

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

@@ -0,0 +1,87 @@
+import { getContext, onDestroy, setContext } from 'svelte';
+import {
+	createFrameRegistry,
+	type FrameCallback,
+	type FrameKey,
+	type FrameProfilingSnapshot,
+	type FrameRegistry,
+	type FrameRunTimings,
+	type FrameScheduleSnapshot,
+	type FrameStage,
+	type FrameStageCallback,
+	type FrameTask,
+	type FrameTaskInvalidation,
+	type FrameTaskInvalidationToken,
+	type UseFrameOptions,
+	type UseFrameResult
+} from '../core/frame-registry.js';
+
+/**
+ * Svelte context key for the active frame registry.
+ */
+const FRAME_CONTEXT_KEY = Symbol('motiongpu.frame-context');
+
+export {
+	createFrameRegistry,
+	type FrameCallback,
+	type FrameKey,
+	type FrameProfilingSnapshot,
+	type FrameRegistry,
+	type FrameRunTimings,
+	type FrameScheduleSnapshot,
+	type FrameStage,
+	type FrameStageCallback,
+	type FrameTask,
+	type FrameTaskInvalidation,
+	type FrameTaskInvalidationToken,
+	type UseFrameOptions,
+	type UseFrameResult
+};
+
+/**
+ * Provides a frame registry through Svelte context.
+ */
+export function provideFrameRegistry(registry: FrameRegistry): void {
+	setContext(FRAME_CONTEXT_KEY, registry);
+}
+
+/**
+ * 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 destroy.
+ */
+export function useFrame(
+	keyOrCallback: FrameKey | FrameCallback,
+	callbackOrOptions?: FrameCallback | UseFrameOptions,
+	maybeOptions?: UseFrameOptions
+): UseFrameResult {
+	const registry = getContext<FrameRegistry>(FRAME_CONTEXT_KEY);
+	if (!registry) {
+		throw new Error('useFrame must be used inside <FragCanvas>');
+	}
+
+	const registration =
+		typeof keyOrCallback === 'function'
+			? registry.register(keyOrCallback, callbackOrOptions as UseFrameOptions | undefined)
+			: registry.register(keyOrCallback, callbackOrOptions as FrameCallback, maybeOptions);
+	onDestroy(registration.unsubscribe);
+
+	return {
+		task: registration.task,
+		start: registration.start,
+		stop: registration.stop,
+		started: registration.started
+	};
+}

package/src/lib/svelte/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Svelte adapter entrypoint for MotionGPU.
+ */
+export { default as FragCanvas } from './FragCanvas.svelte';
+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/src/lib/svelte/motiongpu-context.ts

@@ -0,0 +1,97 @@
+import { getContext, setContext } from 'svelte';
+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';
+
+/**
+ * Svelte context key used to expose `FragCanvas` runtime state.
+ */
+const MOTIONGPU_CONTEXT_KEY = Symbol('motiongpu.context');
+
+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>>;
+
+/**
+ * Public `FragCanvas` runtime context available to hooks and user components.
+ */
+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;
+}
+
+/**
+ * Registers the motiongpu context in the current Svelte component tree.
+ *
+ * @param context - Context payload to provide.
+ */
+export function provideMotionGPUContext(context: MotionGPUContext): void {
+	setContext(MOTIONGPU_CONTEXT_KEY, context);
+}
+
+/**
+ * Returns the active motiongpu context.
+ *
+ * @returns Active context.
+ * @throws {Error} When called outside `<FragCanvas>`.
+ */
+export function useMotionGPU(): MotionGPUContext {
+	const context = getContext<MotionGPUContext>(MOTIONGPU_CONTEXT_KEY);
+	if (!context) {
+		throw new Error('useMotionGPU must be used inside <FragCanvas>');
+	}
+
+	return context;
+}

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

@@ -0,0 +1,145 @@
+import type { CurrentReadable } from '../core/current-value.js';
+import { useMotionGPU, 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);
+}
+
+/**
+ * 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;
+
+	if (namespace === undefined) {
+		const allStore: CurrentReadable<UC> = {
+			get current() {
+				return userStore.current as UC;
+			},
+			subscribe(run) {
+				return userStore.subscribe((context) => run(context as UC));
+			}
+		};
+
+		return allStore;
+	}
+
+	const scopedStore: CurrentReadable<UC[K] | undefined> = {
+		get current() {
+			return userStore.current[namespace] as UC[K] | undefined;
+		},
+		subscribe(run) {
+			return userStore.subscribe((context) => run(context[namespace] as UC[K] | undefined));
+		}
+	};
+
+	return scopedStore;
+}
+
+/**
+ * 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 {
+	const userStore = useMotionGPU().user;
+	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;
+}

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

@@ -0,0 +1,232 @@
+import { onDestroy } from 'svelte';
+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 {@link 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[]);
+
+/**
+ * Supported options input variants for `useTexture`.
+ */
+export type TextureOptionsInput = TextureLoadOptions | (() => TextureLoadOptions);
+
+/**
+ * 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 optionsInput - Loader options object or lazy options provider.
+ * @returns Reactive texture loading state with reload support.
+ */
+export function useTexture(
+	urlInput: TextureUrlInput,
+	optionsInput: TextureOptionsInput = {}
+): UseTextureResult {
+	const textures = currentWritable<LoadedTexture[] | null>(null);
+	const loading = currentWritable(true);
+	const error = currentWritable<Error | null>(null);
+	const errorReport = currentWritable<MotionGPUErrorReport | null>(null);
+	let disposed = false;
+	let requestVersion = 0;
+	let activeController: AbortController | null = null;
+	let runningLoad: Promise<void> | null = null;
+	let reloadQueued = false;
+	const getUrls = typeof urlInput === 'function' ? urlInput : () => urlInput;
+	const getOptions =
+		typeof optionsInput === 'function'
+			? (optionsInput as () => TextureLoadOptions)
+			: () => optionsInput;
+
+	const executeLoad = async (): Promise<void> => {
+		if (disposed) {
+			return;
+		}
+
+		const version = ++requestVersion;
+		const controller = new AbortController();
+		activeController = controller;
+		loading.set(true);
+		error.set(null);
+		errorReport.set(null);
+
+		const previous = textures.current;
+		const options = getOptions() ?? {};
+		const mergedSignal = mergeAbortSignals(controller.signal, options.signal);
+		try {
+			const loaded = await loadTexturesFromUrls(getUrls(), {
+				...options,
+				signal: mergedSignal.signal
+			});
+			if (disposed || version !== requestVersion) {
+				disposeTextures(loaded);
+				return;
+			}
+
+			textures.set(loaded);
+			disposeTextures(previous);
+		} catch (nextError) {
+			if (disposed || version !== requestVersion) {
+				return;
+			}
+
+			if (isAbortError(nextError)) {
+				return;
+			}
+
+			disposeTextures(previous);
+			textures.set(null);
+			const normalizedError = toError(nextError);
+			error.set(normalizedError);
+			errorReport.set(toMotionGPUErrorReport(normalizedError, 'initialization'));
+		} finally {
+			if (!disposed && version === requestVersion) {
+				loading.set(false);
+			}
+			if (activeController === controller) {
+				activeController = null;
+			}
+			mergedSignal.dispose();
+		}
+	};
+
+	const runLoadLoop = async (): Promise<void> => {
+		do {
+			reloadQueued = false;
+			await executeLoad();
+		} while (reloadQueued && !disposed);
+	};
+
+	const load = (): Promise<void> => {
+		activeController?.abort();
+		if (runningLoad) {
+			reloadQueued = true;
+			return runningLoad;
+		}
+
+		const pending = runLoadLoop();
+		const trackedPending = pending.finally(() => {
+			if (runningLoad === trackedPending) {
+				runningLoad = null;
+			}
+		});
+		runningLoad = trackedPending;
+		return trackedPending;
+	};
+
+	void load();
+
+	onDestroy(() => {
+		disposed = true;
+		requestVersion += 1;
+		activeController?.abort();
+		disposeTextures(textures.current);
+	});
+
+	return {
+		textures,
+		loading,
+		error,
+		errorReport,
+		reload: load
+	};
+}