@motion-core/motion-gpu 0.6.0 → 0.8.0

package/src/lib/vue/MotionGPUErrorOverlay.vue

@@ -0,0 +1,518 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import type { MotionGPUErrorReport } from '../core/error-report.js';
+import Portal from './Portal.vue';
+
+interface Props {
+	report: MotionGPUErrorReport;
+}
+
+const props = defineProps<Props>();
+
+/**
+ * Normalizes a string for case-insensitive comparison.
+ */
+function normalizeErrorText(value: string): string {
+	return value
+		.trim()
+		.replace(/[.:!]+$/g, '')
+		.toLowerCase();
+}
+
+/**
+ * Resolves a non-redundant message to display, stripping a duplicated title prefix.
+ */
+function resolveDisplayMessage(value: MotionGPUErrorReport): string {
+	const rawMessage = value.message.trim();
+	if (rawMessage.length === 0) {
+		return '';
+	}
+
+	const normalizedMessage = normalizeErrorText(rawMessage);
+	const normalizedTitle = normalizeErrorText(value.title);
+	if (normalizedMessage === normalizedTitle) {
+		return '';
+	}
+
+	const escapedTitle = value.title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+	const prefixPattern = new RegExp(`^${escapedTitle}\\s*[:\\-|]\\s*`, 'i');
+	const stripped = rawMessage.replace(prefixPattern, '').trim();
+	return stripped.length > 0 ? stripped : rawMessage;
+}
+
+/**
+ * Formats the runtime context payload as a human-readable YAML-ish block.
+ */
+function formatRuntimeContext(context: MotionGPUErrorReport['context']): string {
+	if (!context) {
+		return '';
+	}
+
+	const indentBlock = (value: string, spaces = 2): string => {
+		const prefix = ' '.repeat(spaces);
+		return value
+			.split('\n')
+			.map((line) => `${prefix}${line}`)
+			.join('\n');
+	};
+
+	const formatMaterialSignature = (value: string): string => {
+		const trimmed = value.trim();
+		if (trimmed.length === 0) {
+			return '<empty>';
+		}
+		try {
+			return JSON.stringify(JSON.parse(trimmed), null, 2);
+		} catch {
+			return trimmed;
+		}
+	};
+
+	const lines: string[] = [];
+	if (context.materialSignature) {
+		lines.push('materialSignature:');
+		lines.push(indentBlock(formatMaterialSignature(context.materialSignature)));
+	}
+	if (context.passGraph) {
+		lines.push('passGraph:');
+		lines.push(`  passCount: ${context.passGraph.passCount}`);
+		lines.push(`  enabledPassCount: ${context.passGraph.enabledPassCount}`);
+		lines.push('  inputs:');
+		if (context.passGraph.inputs.length === 0) {
+			lines.push('    - <none>');
+		} else {
+			for (const input of context.passGraph.inputs) {
+				lines.push(`    - ${input}`);
+			}
+		}
+		lines.push('  outputs:');
+		if (context.passGraph.outputs.length === 0) {
+			lines.push('    - <none>');
+		} else {
+			for (const output of context.passGraph.outputs) {
+				lines.push(`    - ${output}`);
+			}
+		}
+	}
+	lines.push('activeRenderTargets:');
+	if (context.activeRenderTargets.length === 0) {
+		lines.push('  - <none>');
+	} else {
+		for (const target of context.activeRenderTargets) {
+			lines.push(`  - ${target}`);
+		}
+	}
+	return lines.join('\n');
+}
+
+const displayMessage = computed(() => resolveDisplayMessage(props.report));
+const showDisplayMessage = computed(() => displayMessage.value.length > 0);
+const detailsText = computed(() => props.report.details.join('\n'));
+const stackText = computed(() => props.report.stack.join('\n'));
+const runtimeContextText = computed(() => formatRuntimeContext(props.report.context));
+const detailsSummary = computed(() =>
+	props.report.source ? 'Additional diagnostics' : 'Technical details'
+);
+</script>
+
+<template>
+	<Portal>
+		<div class="motiongpu-error-overlay" role="presentation">
+			<section
+				class="motiongpu-error-dialog"
+				role="alertdialog"
+				aria-live="assertive"
+				aria-modal="true"
+				data-testid="motiongpu-error"
+			>
+				<header class="motiongpu-error-header">
+					<div class="motiongpu-error-header-top">
+						<div class="motiongpu-error-badges">
+							<div class="motiongpu-error-badge-wrap">
+								<p class="motiongpu-error-badge motiongpu-error-badge-phase">
+									{{ report.phase }}
+								</p>
+							</div>
+							<div class="motiongpu-error-badge-wrap">
+								<p class="motiongpu-error-badge motiongpu-error-badge-severity">
+									{{ report.severity }}
+								</p>
+							</div>
+						</div>
+					</div>
+					<h2 class="motiongpu-error-title">{{ report.title }}</h2>
+					<p class="motiongpu-error-recoverable">
+						Recoverable: <span>{{ report.recoverable ? 'yes' : 'no' }}</span>
+					</p>
+				</header>
+				<div class="motiongpu-error-body">
+					<p v-if="showDisplayMessage" class="motiongpu-error-message">
+						{{ displayMessage }}
+					</p>
+					<p class="motiongpu-error-hint">{{ report.hint }}</p>
+				</div>
+
+				<section v-if="report.source" class="motiongpu-error-source" aria-label="Source">
+					<h3 class="motiongpu-error-source-title">Source</h3>
+					<div class="motiongpu-error-source-frame" role="presentation">
+						<div class="motiongpu-error-source-tabs" role="tablist" aria-label="Source files">
+							<span
+								class="motiongpu-error-source-tab motiongpu-error-source-tab-active"
+								role="tab"
+								aria-selected="true"
+								>{{ report.source.location
+								}}<template v-if="report.source.column"
+									>, col {{ report.source.column }}</template
+								></span
+							>
+							<span class="motiongpu-error-source-tab-spacer" aria-hidden="true"></span>
+						</div>
+
+						<div class="motiongpu-error-source-snippet">
+							<div
+								v-for="snippetLine in report.source.snippet"
+								:key="`snippet-${snippetLine.number}`"
+								class="motiongpu-error-source-row"
+								:class="{
+									'motiongpu-error-source-row-active': snippetLine.highlight
+								}"
+							>
+								<span class="motiongpu-error-source-line">{{ snippetLine.number }}</span>
+								<span class="motiongpu-error-source-code">{{ snippetLine.code || ' ' }}</span>
+							</div>
+						</div>
+					</div>
+				</section>
+
+				<div class="motiongpu-error-sections">
+					<details v-if="report.details.length > 0" class="motiongpu-error-details" open>
+						<summary>{{ detailsSummary }}</summary>
+						<pre>{{ detailsText }}</pre>
+					</details>
+					<details v-if="report.stack.length > 0" class="motiongpu-error-details">
+						<summary>Stack trace</summary>
+						<pre>{{ stackText }}</pre>
+					</details>
+					<details v-if="report.context" class="motiongpu-error-details">
+						<summary>Runtime context</summary>
+						<pre>{{ runtimeContextText }}</pre>
+					</details>
+				</div>
+			</section>
+		</div>
+	</Portal>
+</template>
+
+<style>
+.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-header-top {
+	display: flex;
+	align-items: flex-start;
+	gap: 0.75rem;
+}
+
+.motiongpu-error-badges {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.4rem;
+	flex-wrap: wrap;
+}
+
+.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-badge {
+	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-recoverable {
+	margin: 0;
+	font-size: 0.67rem;
+	line-height: 1.2;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--motiongpu-color-foreground-muted);
+}
+
+.motiongpu-error-recoverable span {
+	font-family: var(--motiongpu-font-mono);
+	color: var(--motiongpu-color-foreground);
+}
+
+.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;
+	}
+
+	.motiongpu-error-header-top {
+		flex-direction: column;
+		align-items: flex-start;
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.motiongpu-error-overlay {
+		backdrop-filter: none;
+	}
+}
+</style>

package/src/lib/vue/Portal.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+
+interface Props {
+	target?: string | HTMLElement | null;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+	target: 'body'
+});
+
+defineSlots<{
+	default(): unknown;
+}>();
+
+/**
+ * Resolves a teleport target to a concrete DOM element, falling back to body.
+ */
+function resolveTargetElement(
+	input: string | HTMLElement | null | undefined
+): HTMLElement | string {
+	if (typeof input === 'string') {
+		if (typeof document === 'undefined') {
+			return input;
+		}
+
+		return document.querySelector<HTMLElement>(input) ?? document.body;
+	}
+
+	if (input) {
+		return input;
+	}
+
+	return typeof document === 'undefined' ? 'body' : document.body;
+}
+
+const teleportTarget = computed(() => resolveTargetElement(props.target));
+</script>
+
+<template>
+	<Teleport :to="teleportTarget">
+		<div class="motiongpu-portal-root">
+			<slot />
+		</div>
+	</Teleport>
+</template>

package/src/lib/vue/advanced.ts

@@ -0,0 +1,32 @@
+/**
+ * Vue adapter advanced entrypoint for MotionGPU.
+ */
+export * from './index.js';
+export { applySchedulerPreset, captureSchedulerDebugSnapshot } from '../core/scheduler-helpers.js';
+export { setMotionGPUUserContext, useMotionGPUUserContext } 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/vue/frame-context.ts

@@ -0,0 +1,96 @@
+import { getCurrentInstance, inject, onBeforeUnmount, provide, type InjectionKey } from 'vue';
+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';
+
+/**
+ * Vue injection key used to expose the active frame registry.
+ */
+export const frameRegistryKey: InjectionKey<FrameRegistry> = Symbol('motiongpu.frame-registry');
+
+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 Vue provide/inject.
+ *
+ * @param registry - Frame registry instance to provide to descendants.
+ */
+export function provideFrameRegistry(registry: FrameRegistry): void {
+	provide(frameRegistryKey, 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
+ * when the owning component is unmounted.
+ *
+ * @throws {Error} When called outside `<FragCanvas>`.
+ * @throws {Error} When the callback is missing.
+ */
+export function useFrame(
+	keyOrCallback: FrameKey | FrameCallback,
+	callbackOrOptions?: FrameCallback | UseFrameOptions,
+	maybeOptions?: UseFrameOptions
+): UseFrameResult {
+	const registry = inject(frameRegistryKey, null);
+	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);
+
+	if (getCurrentInstance()) {
+		onBeforeUnmount(registration.unsubscribe);
+	}
+
+	return {
+		task: registration.task,
+		start: registration.start,
+		stop: registration.stop,
+		started: registration.started
+	};
+}