@motion-core/motion-gpu/dist/core/frame-registry.d.ts

Framework-agnostic WebGPU runtime for fullscreen WGSL shaders with explicit Svelte, React, and Vue adapter entrypoints.

import { type Subscribable } from './current-value.js';
import type { FrameInvalidationToken, FrameState, RenderMode } from './types.js';
/**
 * Per-frame callback executed by the frame scheduler.
 */
export type FrameCallback = (state: FrameState) => void;
/**
 * Stable key type used to identify frame tasks and stages.
 */
export type FrameKey = string | symbol;
/**
 * Public metadata describing a registered frame task.
 */
export interface FrameTask {
    key: FrameKey;
    stage: FrameKey;
}
/**
 * Public metadata describing a frame stage.
 */
export interface FrameStage {
    key: FrameKey;
}
/**
 * Stage callback allowing custom orchestration around task execution.
 */
export type FrameStageCallback = (state: FrameState, runTasks: () => void) => void;
/**
 * Options controlling task registration and scheduling behavior.
 */
export interface UseFrameOptions {
    /**
     * Whether task starts in active state.
     *
     * @default true
     */
    autoStart?: boolean;
    /**
     * Whether task execution invalidates frame automatically.
     *
     * @default true
     */
    autoInvalidate?: boolean;
    /**
     * Explicit task invalidation policy.
     */
    invalidation?: FrameTaskInvalidation;
    /**
     * Stage to register task in.
     *
     * If omitted, main stage is used unless inferred from task dependencies.
     */
    stage?: FrameKey | FrameStage;
    /**
     * Task dependencies that should run after this task.
     */
    before?: (FrameKey | FrameTask) | (FrameKey | FrameTask)[];
    /**
     * Task dependencies that should run before this task.
     */
    after?: (FrameKey | FrameTask) | (FrameKey | FrameTask)[];
    /**
     * Dynamic predicate controlling whether the task is currently active.
     */
    running?: () => boolean;
}
/**
 * Invalidation token value or resolver.
 */
export type FrameTaskInvalidationToken = FrameInvalidationToken | (() => FrameInvalidationToken | null | undefined);
/**
 * Explicit task invalidation policy.
 */
export type FrameTaskInvalidation = 'never' | 'always' | {
    mode?: 'never' | 'always';
    token?: FrameTaskInvalidationToken;
} | {
    mode: 'on-change';
    token: FrameTaskInvalidationToken;
};
/**
 * Handle returned by `useFrame` registration.
 */
export interface UseFrameResult {
    /**
     * Registered task metadata.
     */
    task: FrameTask;
    /**
     * Starts task execution.
     */
    start: () => void;
    /**
     * Stops task execution.
     */
    stop: () => void;
    /**
     * Readable flag representing effective running state.
     */
    started: Subscribable<boolean>;
}
/**
 * Snapshot of the resolved stage/task execution order.
 */
export interface FrameScheduleSnapshot {
    readonly stages: ReadonlyArray<{
        readonly key: string;
        readonly tasks: readonly string[];
    }>;
}
/**
 * Optional scheduler diagnostics payload captured for the last run.
 */
export interface FrameRunTimings {
    readonly total: number;
    readonly stages: Readonly<Record<string, {
        readonly duration: number;
        readonly tasks: Readonly<Record<string, number>>;
    }>>;
}
/**
 * Aggregated timing statistics for stage/task profiling.
 */
export interface FrameTimingStats {
    readonly last: number;
    readonly avg: number;
    readonly min: number;
    readonly max: number;
    readonly count: number;
}
/**
 * Profiling snapshot aggregated from the configured history window.
 */
export interface FrameProfilingSnapshot {
    readonly window: number;
    readonly frameCount: number;
    readonly lastFrame: FrameRunTimings | null;
    readonly total: FrameTimingStats;
    readonly stages: Readonly<Record<string, {
        readonly timings: FrameTimingStats;
        readonly tasks: Readonly<Record<string, FrameTimingStats>>;
    }>>;
}
/**
 * Internal registration payload including unsubscribe callback.
 */
interface RegisteredFrameTask extends UseFrameResult {
    unsubscribe: () => void;
}
/**
 * Default stage key used when task stage is not explicitly specified.
 */
export declare const DEFAULT_FRAME_STAGE_KEY: unique symbol;
/**
 * Resolves the stage metadata a task will receive during registration.
 * Adapter hooks use this before lifecycle effects run so task references are stable.
 */
export declare function resolveFrameTaskStage(options?: UseFrameOptions): FrameKey;
/**
 * Runtime registry that stores frame tasks/stages and drives render scheduling.
 */
export interface FrameRegistry {
    /**
     * Registers a frame callback in the scheduler.
     */
    register: (keyOrCallback: FrameKey | FrameCallback, callbackOrOptions?: FrameCallback | UseFrameOptions, maybeOptions?: UseFrameOptions) => RegisteredFrameTask;
    /**
     * Executes one scheduler run.
     */
    run: (state: FrameState) => void;
    /**
     * Marks frame as invalidated for `on-demand` mode.
     */
    invalidate: (token?: FrameInvalidationToken) => void;
    /**
     * Requests a single render in `manual` mode.
     */
    advance: () => void;
    /**
     * Returns whether renderer should submit a frame now.
     */
    shouldRender: () => boolean;
    /**
     * Resets one-frame invalidation/advance flags.
     */
    endFrame: () => void;
    /**
     * Sets render scheduling mode.
     */
    setRenderMode: (mode: RenderMode) => void;
    /**
     * Enables or disables automatic rendering entirely.
     */
    setAutoRender: (enabled: boolean) => void;
    /**
     * Sets maximum allowed delta passed to frame tasks.
     */
    setMaxDelta: (value: number) => void;
    /**
     * Enables/disables frame profiling.
     */
    setProfilingEnabled: (enabled: boolean) => void;
    /**
     * Sets profiling history window between 1 and 10,000 frames.
     */
    setProfilingWindow: (window: number) => void;
    /**
     * Clears collected profiling samples.
     */
    resetProfiling: () => void;
    /**
     * Enables/disables diagnostics capture.
     */
    setDiagnosticsEnabled: (enabled: boolean) => void;
    /**
     * Returns current render mode.
     */
    getRenderMode: () => RenderMode;
    /**
     * Returns whether automatic rendering is enabled.
     */
    getAutoRender: () => boolean;
    /**
     * Returns current max delta clamp.
     */
    getMaxDelta: () => number;
    /**
     * Returns profiling toggle state.
     */
    getProfilingEnabled: () => boolean;
    /**
     * Returns active profiling history window between 1 and 10,000 frames.
     */
    getProfilingWindow: () => number;
    /**
     * Returns aggregated profiling snapshot.
     */
    getProfilingSnapshot: () => FrameProfilingSnapshot | null;
    /**
     * Returns diagnostics toggle state.
     */
    getDiagnosticsEnabled: () => boolean;
    /**
     * Returns last run timings snapshot when diagnostics are enabled.
     */
    getLastRunTimings: () => FrameRunTimings | null;
    /**
     * Returns dependency-sorted schedule snapshot.
     */
    getSchedule: () => FrameScheduleSnapshot;
    /**
     * Creates or updates a stage.
     */
    createStage: (key: FrameKey, options?: {
        before?: (FrameKey | FrameStage) | (FrameKey | FrameStage)[];
        after?: (FrameKey | FrameStage) | (FrameKey | FrameStage)[];
        callback?: FrameStageCallback | null;
    }) => FrameStage;
    /**
     * Reads stage metadata by key.
     */
    getStage: (key: FrameKey) => FrameStage | undefined;
    /**
     * Removes all tasks from all stages.
     */
    clear: () => void;
}
/**
 * Creates a frame registry used by `FragCanvas` and `useFrame`.
 *
 * @param options - Initial scheduler options.
 * @returns Mutable frame registry instance.
 */
export declare function createFrameRegistry(options?: {
    renderMode?: RenderMode;
    autoRender?: boolean;
    maxDelta?: number;
    profilingEnabled?: boolean;
    profilingWindow?: number;
    diagnosticsEnabled?: boolean;
}): FrameRegistry;
export {};
//# sourceMappingURL=frame-registry.d.ts.map