@motion-core/motion-gpu 0.1.0

package/dist/frame-context.js

@@ -0,0 +1,731 @@
+import { getContext, onDestroy, setContext } from 'svelte';
+import { writable } from 'svelte/store';
+/**
+ * Svelte context key for the active frame registry.
+ */
+const FRAME_CONTEXT_KEY = Symbol('motiongpu.frame-context');
+/**
+ * Default stage key used when task stage is not explicitly specified.
+ */
+const MAIN_STAGE_KEY = Symbol('motiongpu-main-stage');
+const RENDER_MODE_INVALIDATION_TOKEN = Symbol('motiongpu-render-mode-change');
+/**
+ * Default stage callback that runs tasks immediately.
+ */
+const DEFAULT_STAGE_CALLBACK = (_state, runTasks) => runTasks();
+/**
+ * Normalizes scalar-or-array options to array form.
+ */
+function asArray(value) {
+    if (!value) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Normalizes frame keys to readable string labels.
+ */
+function frameKeyToString(key) {
+    return typeof key === 'symbol' ? key.toString() : key;
+}
+/**
+ * Extracts task key from either direct key or task reference.
+ */
+function toTaskKey(reference) {
+    if (typeof reference === 'string' || typeof reference === 'symbol') {
+        return reference;
+    }
+    return reference.key;
+}
+/**
+ * Extracts stage key from either direct key or stage reference.
+ */
+function toStageKey(reference) {
+    if (typeof reference === 'string' || typeof reference === 'symbol') {
+        return reference;
+    }
+    return reference.key;
+}
+/**
+ * Resolves invalidation token from static value or resolver callback.
+ */
+function resolveInvalidationToken(token) {
+    if (token === undefined) {
+        return null;
+    }
+    const resolved = typeof token === 'function' ? token() : token;
+    if (resolved === null || resolved === undefined) {
+        return null;
+    }
+    return resolved;
+}
+/**
+ * Normalizes task invalidation options to runtime representation.
+ */
+function normalizeTaskInvalidation(key, options) {
+    const explicit = options.invalidation;
+    if (explicit === undefined) {
+        if (options.autoInvalidate === false) {
+            return {
+                mode: 'never',
+                lastToken: null,
+                hasToken: false
+            };
+        }
+        return {
+            mode: 'always',
+            token: key,
+            lastToken: null,
+            hasToken: false
+        };
+    }
+    if (explicit === 'never' || explicit === 'always') {
+        if (explicit === 'never') {
+            return {
+                mode: explicit,
+                lastToken: null,
+                hasToken: false
+            };
+        }
+        return {
+            mode: explicit,
+            token: key,
+            lastToken: null,
+            hasToken: false
+        };
+    }
+    const mode = explicit.mode ?? 'always';
+    const token = explicit.token;
+    if (mode === 'on-change' && token === undefined) {
+        throw new Error('Task invalidation mode "on-change" requires a token');
+    }
+    if (mode === 'never') {
+        return {
+            mode,
+            lastToken: null,
+            hasToken: false
+        };
+    }
+    if (mode === 'on-change') {
+        return {
+            mode,
+            token: token,
+            lastToken: null,
+            hasToken: false
+        };
+    }
+    return {
+        mode,
+        token: token ?? key,
+        lastToken: null,
+        hasToken: false
+    };
+}
+/**
+ * Computes aggregate timing stats from sampled durations.
+ */
+function buildTimingStats(samples, last) {
+    if (samples.length === 0) {
+        return {
+            last,
+            avg: 0,
+            min: 0,
+            max: 0,
+            count: 0
+        };
+    }
+    let sum = 0;
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    for (const value of samples) {
+        sum += value;
+        if (value < min) {
+            min = value;
+        }
+        if (value > max) {
+            max = value;
+        }
+    }
+    return {
+        last,
+        avg: sum / samples.length,
+        min,
+        max,
+        count: samples.length
+    };
+}
+/**
+ * Deterministically sorts dependency keys for stable traversal and diagnostics.
+ */
+function sortDependencyKeys(keys) {
+    return Array.from(keys).sort((a, b) => frameKeyToString(a).localeCompare(frameKeyToString(b)));
+}
+/**
+ * Finds one deterministic cycle path in the directed dependency graph.
+ */
+function findDependencyCycle(items, edges) {
+    const visitState = new Map();
+    const stack = [];
+    let cycle = null;
+    const sortedItems = [...items].sort((a, b) => a.order - b.order);
+    const visit = (key) => {
+        visitState.set(key, 1);
+        stack.push(key);
+        for (const childKey of sortDependencyKeys(edges.get(key) ?? [])) {
+            const state = visitState.get(childKey) ?? 0;
+            if (state === 0) {
+                if (visit(childKey)) {
+                    return true;
+                }
+                continue;
+            }
+            if (state === 1) {
+                const cycleStartIndex = stack.findIndex((entry) => entry === childKey);
+                const cyclePath = cycleStartIndex === -1 ? [childKey] : stack.slice(cycleStartIndex);
+                cycle = [...cyclePath, childKey];
+                return true;
+            }
+        }
+        stack.pop();
+        visitState.set(key, 2);
+        return false;
+    };
+    for (const item of sortedItems) {
+        if ((visitState.get(item.key) ?? 0) !== 0) {
+            continue;
+        }
+        if (visit(item.key)) {
+            return cycle;
+        }
+    }
+    return null;
+}
+/**
+ * Topologically sorts items by `before`/`after` dependencies.
+ *
+ * Throws deterministic errors when dependencies are missing or cyclic.
+ */
+function sortByDependencies(items, getBefore, getAfter, options) {
+    const itemsByKey = new Map();
+    for (const item of items) {
+        itemsByKey.set(item.key, item);
+    }
+    const indegree = new Map();
+    const edges = new Map();
+    for (const item of items) {
+        indegree.set(item.key, 0);
+        edges.set(item.key, new Set());
+    }
+    for (const item of items) {
+        for (const dependencyKey of getAfter(item)) {
+            if (!itemsByKey.has(dependencyKey)) {
+                if (options.isKnownExternalDependency?.(dependencyKey)) {
+                    continue;
+                }
+                throw new Error(`${options.graphName} dependency error: ${options.getItemLabel(item)} references missing dependency "${frameKeyToString(dependencyKey)}" in "after".`);
+            }
+            edges.get(dependencyKey)?.add(item.key);
+            indegree.set(item.key, (indegree.get(item.key) ?? 0) + 1);
+        }
+        for (const dependencyKey of getBefore(item)) {
+            if (!itemsByKey.has(dependencyKey)) {
+                if (options.isKnownExternalDependency?.(dependencyKey)) {
+                    continue;
+                }
+                throw new Error(`${options.graphName} dependency error: ${options.getItemLabel(item)} references missing dependency "${frameKeyToString(dependencyKey)}" in "before".`);
+            }
+            edges.get(item.key)?.add(dependencyKey);
+            indegree.set(dependencyKey, (indegree.get(dependencyKey) ?? 0) + 1);
+        }
+    }
+    const queue = items.filter((item) => (indegree.get(item.key) ?? 0) === 0);
+    queue.sort((a, b) => a.order - b.order);
+    const ordered = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+        ordered.push(current);
+        for (const childKey of edges.get(current.key) ?? []) {
+            const nextDegree = (indegree.get(childKey) ?? 0) - 1;
+            indegree.set(childKey, nextDegree);
+            if (nextDegree === 0) {
+                const child = itemsByKey.get(childKey);
+                if (child) {
+                    queue.push(child);
+                    queue.sort((a, b) => a.order - b.order);
+                }
+            }
+        }
+    }
+    if (ordered.length !== items.length) {
+        const cycle = findDependencyCycle(items, edges);
+        if (cycle) {
+            throw new Error(`${options.graphName} dependency cycle detected: ${cycle.map((key) => frameKeyToString(key)).join(' -> ')}`);
+        }
+        throw new Error(`${options.graphName} dependency resolution failed.`);
+    }
+    return ordered;
+}
+/**
+ * Creates a frame registry used by `FragCanvas` and `useFrame`.
+ *
+ * @param options - Initial scheduler options.
+ * @returns Mutable frame registry instance.
+ */
+export function createFrameRegistry(options) {
+    let renderMode = options?.renderMode ?? 'always';
+    let autoRender = options?.autoRender ?? true;
+    let maxDelta = options?.maxDelta ?? 0.1;
+    let profilingEnabled = options?.profilingEnabled ?? options?.diagnosticsEnabled ?? false;
+    let profilingWindow = options?.profilingWindow ?? 120;
+    let lastRunTimings = null;
+    const profilingHistory = [];
+    let hasUntokenizedInvalidation = true;
+    const invalidationTokens = new Set();
+    let shouldAdvance = false;
+    let orderCounter = 0;
+    const assertMaxDelta = (value) => {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new Error('maxDelta must be a finite number greater than 0');
+        }
+        return value;
+    };
+    const assertProfilingWindow = (value) => {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new Error('profilingWindow must be a finite number greater than 0');
+        }
+        return Math.floor(value);
+    };
+    maxDelta = assertMaxDelta(maxDelta);
+    profilingWindow = assertProfilingWindow(profilingWindow);
+    const stages = new Map();
+    let scheduleDirty = true;
+    let sortedStages = [];
+    const sortedTasksByStage = new Map();
+    let scheduleSnapshot = { stages: [] };
+    const markScheduleDirty = () => {
+        scheduleDirty = true;
+    };
+    const syncSchedule = () => {
+        if (!scheduleDirty) {
+            return;
+        }
+        const stageList = sortByDependencies(Array.from(stages.values()), (stage) => stage.before, (stage) => stage.after, {
+            graphName: 'Frame stage graph',
+            getItemLabel: (stage) => `stage "${frameKeyToString(stage.key)}"`
+        });
+        const nextTasksByStage = new Map();
+        const globalTaskKeys = new Set();
+        for (const stage of stageList) {
+            for (const task of stage.tasks.values()) {
+                globalTaskKeys.add(task.task.key);
+            }
+        }
+        for (const stage of stageList) {
+            const taskList = sortByDependencies(Array.from(stage.tasks.values()).map((task) => ({
+                key: task.task.key,
+                order: task.order,
+                task
+            })), (task) => task.task.before, (task) => task.task.after, {
+                graphName: `Frame task graph for stage "${frameKeyToString(stage.key)}"`,
+                getItemLabel: (task) => `task "${frameKeyToString(task.key)}"`,
+                isKnownExternalDependency: (key) => globalTaskKeys.has(key)
+            }).map((task) => task.task);
+            nextTasksByStage.set(stage.key, taskList);
+        }
+        sortedStages = stageList;
+        sortedTasksByStage.clear();
+        for (const [stageKey, taskList] of nextTasksByStage) {
+            sortedTasksByStage.set(stageKey, taskList);
+        }
+        scheduleSnapshot = {
+            stages: sortedStages.map((stage) => ({
+                key: frameKeyToString(stage.key),
+                tasks: (sortedTasksByStage.get(stage.key) ?? []).map((task) => frameKeyToString(task.task.key))
+            }))
+        };
+        scheduleDirty = false;
+    };
+    const pushProfile = (timings) => {
+        profilingHistory.push(timings);
+        while (profilingHistory.length > profilingWindow) {
+            profilingHistory.shift();
+        }
+    };
+    const clearProfiling = () => {
+        profilingHistory.length = 0;
+        lastRunTimings = null;
+    };
+    const buildProfilingSnapshot = () => {
+        if (!profilingEnabled) {
+            return null;
+        }
+        const stageBuckets = new Map();
+        const totalDurations = [];
+        for (const frame of profilingHistory) {
+            totalDurations.push(frame.total);
+            for (const [stageKey, stageTiming] of Object.entries(frame.stages)) {
+                const stageBucket = stageBuckets.get(stageKey) ?? {
+                    durations: [],
+                    taskDurations: new Map()
+                };
+                stageBucket.durations.push(stageTiming.duration);
+                for (const [taskKey, taskDuration] of Object.entries(stageTiming.tasks)) {
+                    const bucket = stageBucket.taskDurations.get(taskKey) ?? [];
+                    bucket.push(taskDuration);
+                    stageBucket.taskDurations.set(taskKey, bucket);
+                }
+                stageBuckets.set(stageKey, stageBucket);
+            }
+        }
+        const stagesSnapshot = {};
+        for (const [stageKey, stageBucket] of stageBuckets) {
+            const lastStageDuration = lastRunTimings?.stages[stageKey]?.duration ?? 0;
+            const taskSnapshot = {};
+            for (const [taskKey, taskDurations] of stageBucket.taskDurations) {
+                const lastTaskDuration = lastRunTimings?.stages[stageKey]?.tasks[taskKey] ?? 0;
+                taskSnapshot[taskKey] = buildTimingStats(taskDurations, lastTaskDuration);
+            }
+            stagesSnapshot[stageKey] = {
+                timings: buildTimingStats(stageBucket.durations, lastStageDuration),
+                tasks: taskSnapshot
+            };
+        }
+        return {
+            window: profilingWindow,
+            frameCount: profilingHistory.length,
+            lastFrame: lastRunTimings,
+            total: buildTimingStats(totalDurations, lastRunTimings?.total ?? 0),
+            stages: stagesSnapshot
+        };
+    };
+    const ensureStage = (stageReference, stageOptions) => {
+        const stageKey = toStageKey(stageReference);
+        const existing = stages.get(stageKey);
+        if (existing) {
+            if (stageOptions?.before !== undefined) {
+                existing.before = new Set(stageOptions.before.map((entry) => toStageKey(entry)));
+                markScheduleDirty();
+            }
+            if (stageOptions?.after !== undefined) {
+                existing.after = new Set(stageOptions.after.map((entry) => toStageKey(entry)));
+                markScheduleDirty();
+            }
+            if (stageOptions && Object.prototype.hasOwnProperty.call(stageOptions, 'callback')) {
+                existing.callback = stageOptions.callback ?? DEFAULT_STAGE_CALLBACK;
+            }
+            return existing;
+        }
+        const stage = {
+            key: stageKey,
+            order: orderCounter++,
+            started: true,
+            before: new Set((stageOptions?.before ?? []).map((entry) => toStageKey(entry))),
+            after: new Set((stageOptions?.after ?? []).map((entry) => toStageKey(entry))),
+            callback: stageOptions?.callback ?? DEFAULT_STAGE_CALLBACK,
+            tasks: new Map()
+        };
+        stages.set(stageKey, stage);
+        markScheduleDirty();
+        return stage;
+    };
+    ensureStage(MAIN_STAGE_KEY);
+    const resolveEffectiveRunning = (task) => {
+        const running = task.started && (task.running?.() ?? true);
+        if (task.lastRunning !== running) {
+            task.lastRunning = running;
+            task.startedStoreSet(running);
+        }
+        return running;
+    };
+    const hasPendingInvalidation = () => {
+        return hasUntokenizedInvalidation || invalidationTokens.size > 0;
+    };
+    const invalidateWithToken = (token) => {
+        if (token === undefined) {
+            hasUntokenizedInvalidation = true;
+            return;
+        }
+        invalidationTokens.add(token);
+    };
+    const applyTaskInvalidation = (task) => {
+        const config = task.invalidation;
+        if (config.mode === 'never') {
+            return;
+        }
+        if (config.mode === 'always') {
+            const token = resolveInvalidationToken(config.token);
+            invalidateWithToken(token ?? task.task.key);
+            return;
+        }
+        const token = resolveInvalidationToken(config.token);
+        if (token === null) {
+            config.hasToken = false;
+            config.lastToken = null;
+            return;
+        }
+        const changed = !config.hasToken || config.lastToken !== token;
+        config.hasToken = true;
+        config.lastToken = token;
+        if (changed) {
+            invalidateWithToken(token);
+        }
+    };
+    return {
+        register(keyOrCallback, callbackOrOptions, maybeOptions) {
+            const key = typeof keyOrCallback === 'function'
+                ? Symbol('motiongpu-task')
+                : keyOrCallback;
+            const callback = typeof keyOrCallback === 'function' ? keyOrCallback : callbackOrOptions;
+            const taskOptions = typeof keyOrCallback === 'function'
+                ? (callbackOrOptions ?? {})
+                : (maybeOptions ?? {});
+            if (typeof callback !== 'function') {
+                throw new Error('useFrame requires a callback');
+            }
+            const before = asArray(taskOptions.before);
+            const after = asArray(taskOptions.after);
+            const inferredStage = [...before, ...after].find((entry) => typeof entry === 'object' && entry !== null && 'stage' in entry);
+            const stageKey = taskOptions.stage
+                ? toStageKey(taskOptions.stage)
+                : (inferredStage?.stage ?? MAIN_STAGE_KEY);
+            const stage = ensureStage(stageKey);
+            const startedWritable = writable(taskOptions.autoStart ?? true);
+            const internalTask = {
+                task: { key, stage: stage.key },
+                callback,
+                order: orderCounter++,
+                started: taskOptions.autoStart ?? true,
+                lastRunning: taskOptions.autoStart ?? true,
+                startedStoreSet: startedWritable.set,
+                startedStore: { subscribe: startedWritable.subscribe },
+                before: new Set(before.map((entry) => toTaskKey(entry))),
+                after: new Set(after.map((entry) => toTaskKey(entry))),
+                invalidation: normalizeTaskInvalidation(key, taskOptions)
+            };
+            if (taskOptions.running) {
+                internalTask.running = taskOptions.running;
+            }
+            stage.tasks.set(key, internalTask);
+            markScheduleDirty();
+            internalTask.startedStoreSet(resolveEffectiveRunning(internalTask));
+            const start = () => {
+                internalTask.started = true;
+                resolveEffectiveRunning(internalTask);
+            };
+            const stop = () => {
+                internalTask.started = false;
+                resolveEffectiveRunning(internalTask);
+            };
+            return {
+                task: internalTask.task,
+                start,
+                stop,
+                started: internalTask.startedStore,
+                unsubscribe: () => {
+                    if (stage.tasks.delete(key)) {
+                        markScheduleDirty();
+                    }
+                }
+            };
+        },
+        run(state) {
+            const clampedDelta = Math.min(state.delta, maxDelta);
+            const frameState = clampedDelta === state.delta
+                ? state
+                : {
+                    ...state,
+                    delta: clampedDelta
+                };
+            syncSchedule();
+            const frameStart = profilingEnabled ? performance.now() : 0;
+            const stageTimings = {};
+            for (const stage of sortedStages) {
+                if (!stage.started) {
+                    continue;
+                }
+                const stageStart = profilingEnabled ? performance.now() : 0;
+                const taskTimings = {};
+                const taskList = sortedTasksByStage.get(stage.key) ?? [];
+                stage.callback(frameState, () => {
+                    for (const task of taskList) {
+                        if (!resolveEffectiveRunning(task)) {
+                            continue;
+                        }
+                        const taskStart = profilingEnabled ? performance.now() : 0;
+                        task.callback(frameState);
+                        if (profilingEnabled) {
+                            taskTimings[frameKeyToString(task.task.key)] = performance.now() - taskStart;
+                        }
+                        applyTaskInvalidation(task);
+                    }
+                });
+                if (profilingEnabled) {
+                    stageTimings[frameKeyToString(stage.key)] = {
+                        duration: performance.now() - stageStart,
+                        tasks: taskTimings
+                    };
+                }
+            }
+            if (profilingEnabled) {
+                const timings = {
+                    total: performance.now() - frameStart,
+                    stages: stageTimings
+                };
+                lastRunTimings = timings;
+                pushProfile(timings);
+            }
+        },
+        invalidate(token) {
+            invalidateWithToken(token);
+        },
+        advance() {
+            shouldAdvance = true;
+            invalidateWithToken();
+        },
+        shouldRender() {
+            if (!autoRender) {
+                return false;
+            }
+            if (renderMode === 'always') {
+                return true;
+            }
+            if (renderMode === 'on-demand') {
+                return shouldAdvance || hasPendingInvalidation();
+            }
+            return shouldAdvance;
+        },
+        endFrame() {
+            hasUntokenizedInvalidation = false;
+            invalidationTokens.clear();
+            shouldAdvance = false;
+        },
+        setRenderMode(mode) {
+            if (renderMode === mode) {
+                return;
+            }
+            renderMode = mode;
+            shouldAdvance = false;
+            if (mode === 'on-demand') {
+                invalidateWithToken(RENDER_MODE_INVALIDATION_TOKEN);
+            }
+        },
+        setAutoRender(enabled) {
+            autoRender = enabled;
+        },
+        setMaxDelta(value) {
+            maxDelta = assertMaxDelta(value);
+        },
+        setProfilingEnabled(enabled) {
+            profilingEnabled = enabled;
+            if (!enabled) {
+                clearProfiling();
+            }
+        },
+        setProfilingWindow(window) {
+            profilingWindow = assertProfilingWindow(window);
+            while (profilingHistory.length > profilingWindow) {
+                profilingHistory.shift();
+            }
+        },
+        resetProfiling() {
+            clearProfiling();
+        },
+        setDiagnosticsEnabled(enabled) {
+            profilingEnabled = enabled;
+            if (!enabled) {
+                clearProfiling();
+            }
+        },
+        getRenderMode() {
+            return renderMode;
+        },
+        getAutoRender() {
+            return autoRender;
+        },
+        getMaxDelta() {
+            return maxDelta;
+        },
+        getProfilingEnabled() {
+            return profilingEnabled;
+        },
+        getProfilingWindow() {
+            return profilingWindow;
+        },
+        getProfilingSnapshot() {
+            return buildProfilingSnapshot();
+        },
+        getDiagnosticsEnabled() {
+            return profilingEnabled;
+        },
+        getLastRunTimings() {
+            return lastRunTimings;
+        },
+        getSchedule() {
+            syncSchedule();
+            return scheduleSnapshot;
+        },
+        createStage(key, options) {
+            const stageOptions = options
+                ? {
+                    ...(Object.prototype.hasOwnProperty.call(options, 'before')
+                        ? { before: asArray(options.before) }
+                        : {}),
+                    ...(Object.prototype.hasOwnProperty.call(options, 'after')
+                        ? { after: asArray(options.after) }
+                        : {}),
+                    ...(Object.prototype.hasOwnProperty.call(options, 'callback')
+                        ? { callback: options.callback ?? null }
+                        : {})
+                }
+                : undefined;
+            const stage = ensureStage(key, stageOptions);
+            return { key: stage.key };
+        },
+        getStage(key) {
+            const stage = stages.get(key);
+            if (!stage) {
+                return undefined;
+            }
+            return { key: stage.key };
+        },
+        clear() {
+            for (const stage of stages.values()) {
+                stage.tasks.clear();
+            }
+            markScheduleDirty();
+        }
+    };
+}
+/**
+ * Provides a frame registry through Svelte context.
+ *
+ * @param registry - Registry to provide.
+ */
+export function provideFrameRegistry(registry) {
+    setContext(FRAME_CONTEXT_KEY, registry);
+}
+/**
+ * Registers a callback in the active frame registry and auto-unsubscribes on destroy.
+ *
+ * @returns Frame task handle for start/stop control.
+ * @throws {Error} When used outside `<FragCanvas>`.
+ */
+export function useFrame(keyOrCallback, callbackOrOptions, maybeOptions) {
+    const registry = getContext(FRAME_CONTEXT_KEY);
+    if (!registry) {
+        throw new Error('useFrame must be used inside <FragCanvas>');
+    }
+    const registration = typeof keyOrCallback === 'function'
+        ? registry.register(keyOrCallback, callbackOrOptions)
+        : registry.register(keyOrCallback, callbackOrOptions, maybeOptions);
+    onDestroy(registration.unsubscribe);
+    return {
+        task: registration.task,
+        start: registration.start,
+        stop: registration.stop,
+        started: registration.started
+    };
+}