@motion-core/motion-gpu 0.4.0 → 0.4.2

package/src/lib/react/MotionGPUErrorOverlay.tsx

@@ -0,0 +1,392 @@
+import type { MotionGPUErrorReport } from '../core/error-report.js';
+import { Portal } from './Portal.js';
+
+interface MotionGPUErrorOverlayProps {
+	report: MotionGPUErrorReport;
+}
+
+const MOTIONGPU_ERROR_OVERLAY_STYLES = `
+.motiongpu-error-overlay {
+	--motiongpu-base-hue: var(--base-hue, 265);
+	--motiongpu-color-background: oklch(0.2178 0.0056 var(--motiongpu-base-hue));
+	--motiongpu-color-background-muted: oklch(0.261 0.007 var(--motiongpu-base-hue));
+	--motiongpu-color-foreground: oklch(1 0 0);
+	--motiongpu-color-foreground-muted: oklch(0.6699 0.0081 var(--motiongpu-base-hue));
+	--motiongpu-color-card: var(--motiongpu-color-background);
+	--motiongpu-color-accent: oklch(0.6996 0.181959 44.4414);
+	--motiongpu-color-accent-secondary: oklch(0.5096 0.131959 44.4414);
+	--motiongpu-color-border: oklch(0.928 0.013 var(--motiongpu-base-hue) / 0.05);
+	--motiongpu-color-white-fixed: oklch(1 0 0);
+	--motiongpu-shadow-card: var(
+		--shadow-2xl,
+		0px 1px 1px -0.5px rgba(0, 0, 0, 0.06),
+		0px 3px 3px -1.5px rgba(0, 0, 0, 0.06),
+		0px 6px 6px -3px rgba(0, 0, 0, 0.06),
+		0px 12px 12px -6px rgba(0, 0, 0, 0.06),
+		0px 24px 24px -12px rgba(0, 0, 0, 0.05),
+		0px 48px 48px -24px rgba(0, 0, 0, 0.06)
+	);
+	--motiongpu-radius-md: var(--radius-md, 0.5rem);
+	--motiongpu-radius-lg: var(--radius-lg, 0.75rem);
+	--motiongpu-radius-xl: var(--radius-xl, 1rem);
+	--motiongpu-font-sans: var(
+		--font-sans,
+		'Inter',
+		'Segoe UI',
+		'Helvetica Neue',
+		Arial,
+		sans-serif
+	);
+	--motiongpu-font-mono: var(--font-mono, 'SFMono-Regular', 'Menlo', 'Consolas', monospace);
+	position: fixed;
+	inset: 0;
+	display: grid;
+	place-items: center;
+	padding: clamp(0.75rem, 1.4vw, 1.5rem);
+	background: rgba(0, 0, 0, 0.8);
+	backdrop-filter: blur(10px);
+	z-index: 2147483647;
+	font-family: var(--motiongpu-font-sans);
+	color-scheme: dark;
+}
+
+.motiongpu-error-dialog {
+	width: min(52rem, calc(100vw - 1.5rem));
+	max-height: min(84vh, 44rem);
+	overflow: auto;
+	margin: 0;
+	padding: 1.1rem;
+	border: 1px solid var(--motiongpu-color-border);
+	border-radius: var(--motiongpu-radius-xl);
+	max-width: calc(100vw - 1.5rem);
+	box-sizing: border-box;
+	font-size: 0.875rem;
+	font-weight: 400;
+	line-height: 1.45;
+	background: var(--motiongpu-color-card);
+	color: var(--motiongpu-color-foreground);
+	box-shadow: var(--motiongpu-shadow-card);
+}
+
+.motiongpu-error-header {
+	display: grid;
+	gap: 0.55rem;
+	padding-bottom: 0.9rem;
+	border-bottom: 1px solid var(--motiongpu-color-border);
+}
+
+.motiongpu-error-badge-wrap {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.4rem;
+	width: fit-content;
+	padding: 0.18rem;
+	border-radius: 999px;
+	border: 1px solid var(--motiongpu-color-border);
+	background: var(--motiongpu-color-background-muted);
+}
+
+.motiongpu-error-phase {
+	display: inline-flex;
+	align-items: center;
+	margin: 0;
+	padding: 0.22rem 0.56rem;
+	border-radius: 999px;
+	font-size: 0.66rem;
+	letter-spacing: 0.08em;
+	line-height: 1;
+	font-weight: 500;
+	text-transform: uppercase;
+	color: var(--motiongpu-color-white-fixed);
+	background: linear-gradient(
+		180deg,
+		var(--motiongpu-color-accent) 0%,
+		var(--motiongpu-color-accent-secondary) 100%
+	);
+	box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.24);
+}
+
+.motiongpu-error-title {
+	margin: 0;
+	font-size: clamp(1.02rem, 1vw + 0.72rem, 1.32rem);
+	font-weight: 500;
+	line-height: 1.18;
+	letter-spacing: -0.02em;
+	text-wrap: balance;
+	color: var(--motiongpu-color-foreground);
+}
+
+.motiongpu-error-body {
+	display: grid;
+	gap: 0.62rem;
+	margin-top: 0.92rem;
+}
+
+.motiongpu-error-message {
+	margin: 0;
+	padding: 0.72rem 0.78rem;
+	border: 1px solid color-mix(in oklch, var(--motiongpu-color-accent) 28%, transparent);
+	border-radius: var(--motiongpu-radius-md);
+	background: color-mix(in oklch, var(--motiongpu-color-accent) 10%, transparent);
+	font-size: 0.82rem;
+	line-height: 1.4;
+	font-weight: 400;
+	color: var(--motiongpu-color-foreground);
+}
+
+.motiongpu-error-hint {
+	margin: 0;
+	font-size: 0.82rem;
+	line-height: 1.45;
+	font-weight: 400;
+	color: var(--motiongpu-color-foreground-muted);
+}
+
+.motiongpu-error-sections {
+	display: grid;
+	gap: 0.62rem;
+	margin-top: 0.95rem;
+}
+
+.motiongpu-error-source {
+	display: grid;
+	gap: 0.48rem;
+	margin-top: 0.96rem;
+}
+
+.motiongpu-error-source-title {
+	margin: 0;
+	font-size: 0.8rem;
+	font-weight: 500;
+	line-height: 1.3;
+	letter-spacing: 0.045em;
+	text-transform: uppercase;
+	color: var(--motiongpu-color-foreground);
+}
+
+.motiongpu-error-source-frame {
+	border: 1px solid var(--motiongpu-color-border);
+	border-radius: var(--motiongpu-radius-lg);
+	overflow: hidden;
+	background: var(--motiongpu-color-background-muted);
+}
+
+.motiongpu-error-source-tabs {
+	display: flex;
+	align-items: stretch;
+	border-bottom: 1px solid var(--motiongpu-color-border);
+	background: var(--motiongpu-color-background);
+}
+
+.motiongpu-error-source-tab {
+	display: inline-flex;
+	align-items: center;
+	padding: 0.5rem 0.68rem;
+	font-size: 0.76rem;
+	font-weight: 400;
+	line-height: 1.2;
+	color: var(--motiongpu-color-foreground-muted);
+	border-right: 1px solid var(--motiongpu-color-border);
+}
+
+.motiongpu-error-source-tab-active {
+	color: var(--motiongpu-color-foreground);
+	background: var(--motiongpu-color-background-muted);
+}
+
+.motiongpu-error-source-tab-spacer {
+	flex: 1 1 auto;
+}
+
+.motiongpu-error-source-snippet {
+	display: grid;
+	background: var(--motiongpu-color-background-muted);
+}
+
+.motiongpu-error-source-row {
+	display: grid;
+	grid-template-columns: 2rem minmax(0, 1fr);
+	align-items: start;
+	gap: 0.42rem;
+	padding: 0.2rem 0.68rem;
+}
+
+.motiongpu-error-source-row-active {
+	background: color-mix(in oklch, var(--motiongpu-color-accent) 10%, transparent);
+}
+
+.motiongpu-error-source-line {
+	font-family: var(--motiongpu-font-mono);
+	font-size: 0.77rem;
+	font-weight: 400;
+	line-height: 1.3;
+	font-variant-numeric: tabular-nums;
+	font-feature-settings: 'tnum' 1;
+	border-right: 1px solid var(--motiongpu-color-border);
+	color: var(--motiongpu-color-foreground-muted);
+	text-align: left;
+}
+
+.motiongpu-error-source-code {
+	font-family: var(--motiongpu-font-mono);
+	font-size: 0.77rem;
+	font-weight: 400;
+	line-height: 1.3;
+	color: var(--motiongpu-color-foreground);
+	white-space: pre-wrap;
+	word-break: break-word;
+}
+
+.motiongpu-error-details {
+	border: 1px solid var(--motiongpu-color-border);
+	border-radius: var(--motiongpu-radius-lg);
+	overflow: hidden;
+	background: var(--motiongpu-color-background);
+}
+
+.motiongpu-error-details summary {
+	cursor: pointer;
+	padding: 0.56rem 0.68rem;
+	font-size: 0.7rem;
+	letter-spacing: 0.07em;
+	line-height: 1.2;
+	font-weight: 500;
+	text-transform: uppercase;
+	color: var(--motiongpu-color-foreground);
+}
+
+.motiongpu-error-details[open] summary {
+	border-bottom: 1px solid var(--motiongpu-color-border);
+}
+
+.motiongpu-error-details pre {
+	margin: 0;
+	padding: 0.62rem 0.68rem;
+	white-space: pre-wrap;
+	word-break: break-word;
+	overflow: auto;
+	background: var(--motiongpu-color-background-muted);
+	font-size: 0.74rem;
+	line-height: 1.4;
+	font-weight: 400;
+	color: var(--motiongpu-color-foreground);
+	font-family: var(--motiongpu-font-mono);
+}
+
+@media (max-width: 42rem) {
+	.motiongpu-error-overlay {
+		padding: 0.62rem;
+	}
+
+	.motiongpu-error-dialog {
+		padding: 0.85rem;
+	}
+
+	.motiongpu-error-title {
+		font-size: 1.02rem;
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.motiongpu-error-overlay {
+		backdrop-filter: none;
+	}
+}
+`;
+
+function normalizeErrorText(value: string): string {
+	return value
+		.trim()
+		.replace(/[.:!]+$/g, '')
+		.toLowerCase();
+}
+
+function shouldShowErrorMessage(value: MotionGPUErrorReport): boolean {
+	return normalizeErrorText(value.message) !== normalizeErrorText(value.title);
+}
+
+export function MotionGPUErrorOverlay({ report }: MotionGPUErrorOverlayProps) {
+	const detailsSummary = report.source ? 'Additional diagnostics' : 'Technical details';
+
+	return (
+		<Portal>
+			<style>{MOTIONGPU_ERROR_OVERLAY_STYLES}</style>
+			<div className="motiongpu-error-overlay" role="presentation">
+				<section
+					className="motiongpu-error-dialog"
+					role="alertdialog"
+					aria-live="assertive"
+					aria-modal="true"
+					data-testid="motiongpu-error"
+				>
+					<header className="motiongpu-error-header">
+						<div className="motiongpu-error-badge-wrap">
+							<p className="motiongpu-error-phase">{report.phase}</p>
+						</div>
+						<h2 className="motiongpu-error-title">{report.title}</h2>
+					</header>
+					<div className="motiongpu-error-body">
+						{shouldShowErrorMessage(report) ? (
+							<p className="motiongpu-error-message">{report.message}</p>
+						) : null}
+						<p className="motiongpu-error-hint">{report.hint}</p>
+					</div>
+
+					{report.source ? (
+						<section className="motiongpu-error-source" aria-label="Source">
+							<h3 className="motiongpu-error-source-title">Source</h3>
+							<div className="motiongpu-error-source-frame" role="presentation">
+								<div
+									className="motiongpu-error-source-tabs"
+									role="tablist"
+									aria-label="Source files"
+								>
+									<span
+										className="motiongpu-error-source-tab motiongpu-error-source-tab-active"
+										role="tab"
+										aria-selected="true"
+									>
+										{report.source.location}
+										{report.source.column ? `, col ${report.source.column}` : ''}
+									</span>
+									<span className="motiongpu-error-source-tab-spacer" aria-hidden="true"></span>
+								</div>
+
+								<div className="motiongpu-error-source-snippet">
+									{report.source.snippet.map((snippetLine) => (
+										<div
+											key={`snippet-${snippetLine.number}`}
+											className={
+												snippetLine.highlight
+													? 'motiongpu-error-source-row motiongpu-error-source-row-active'
+													: 'motiongpu-error-source-row'
+											}
+										>
+											<span className="motiongpu-error-source-line">{snippetLine.number}</span>
+											<span className="motiongpu-error-source-code">{snippetLine.code || ' '}</span>
+										</div>
+									))}
+								</div>
+							</div>
+						</section>
+					) : null}
+
+					<div className="motiongpu-error-sections">
+						{report.details.length > 0 ? (
+							<details className="motiongpu-error-details" open>
+								<summary>{detailsSummary}</summary>
+								<pre>{report.details.join('\n')}</pre>
+							</details>
+						) : null}
+						{report.stack.length > 0 ? (
+							<details className="motiongpu-error-details">
+								<summary>Stack trace</summary>
+								<pre>{report.stack.join('\n')}</pre>
+							</details>
+						) : null}
+					</div>
+				</section>
+			</div>
+		</Portal>
+	);
+}

package/src/lib/react/advanced.ts

@@ -0,0 +1,36 @@
+/**
+ * React adapter advanced entrypoint for MotionGPU.
+ */
+export * from './index.js';
+export { applySchedulerPreset, captureSchedulerDebugSnapshot } from '../core/scheduler-helpers.js';
+export {
+	setMotionGPUUserContext,
+	useMotionGPUUserContext,
+	useSetMotionGPUUserContext
+} from './use-motiongpu-user-context.js';
+export type {
+	ApplySchedulerPresetOptions,
+	SchedulerDebugSnapshot,
+	SchedulerPreset,
+	SchedulerPresetConfig
+} from '../core/scheduler-helpers.js';
+export type { MotionGPUUserContext, MotionGPUUserNamespace } from './motiongpu-context.js';
+export type {
+	FrameProfilingSnapshot,
+	FrameKey,
+	FrameTaskInvalidation,
+	FrameTaskInvalidationToken,
+	FrameRunTimings,
+	FrameScheduleSnapshot,
+	FrameStage,
+	FrameStageCallback,
+	FrameTimingStats,
+	FrameTask
+} from '../core/frame-registry.js';
+export type { SetMotionGPUUserContextOptions } from './use-motiongpu-user-context.js';
+export type {
+	RenderPassContext,
+	RenderTarget,
+	UniformLayout,
+	UniformLayoutEntry
+} from '../core/types.js';

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,51 @@
+/**
+ * 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';