@motion-core/motion-gpu 0.1.0

package/dist/core/uniforms.js

@@ -0,0 +1,222 @@
+/**
+ * Valid WGSL identifier pattern used for uniform and texture keys.
+ */
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Rounds a value up to the nearest multiple of `alignment`.
+ */
+function roundUp(value, alignment) {
+    return Math.ceil(value / alignment) * alignment;
+}
+/**
+ * Returns WGSL std140-like alignment and size metadata for a uniform type.
+ */
+function getTypeLayout(type) {
+    switch (type) {
+        case 'f32':
+            return { alignment: 4, size: 4 };
+        case 'vec2f':
+            return { alignment: 8, size: 8 };
+        case 'vec3f':
+            return { alignment: 16, size: 12 };
+        case 'vec4f':
+            return { alignment: 16, size: 16 };
+        case 'mat4x4f':
+            return { alignment: 16, size: 64 };
+        default:
+            throw new Error(`Unsupported uniform type: ${type}`);
+    }
+}
+/**
+ * Type guard for explicitly typed uniform objects.
+ */
+function isTypedUniformValue(value) {
+    return typeof value === 'object' && value !== null && 'type' in value && 'value' in value;
+}
+/**
+ * Validates numeric tuple input with a fixed length.
+ */
+function isTuple(value, size) {
+    return (Array.isArray(value) &&
+        value.length === size &&
+        value.every((entry) => typeof entry === 'number' && Number.isFinite(entry)));
+}
+/**
+ * Type guard for accepted 4x4 matrix uniform values.
+ */
+function isMat4Value(value) {
+    if (value instanceof Float32Array) {
+        return value.length === 16;
+    }
+    return (Array.isArray(value) &&
+        value.length === 16 &&
+        value.every((entry) => typeof entry === 'number' && Number.isFinite(entry)));
+}
+/**
+ * Asserts that a name can be safely used as a WGSL identifier.
+ *
+ * @param name - Candidate uniform/texture name.
+ * @throws {Error} When the identifier is invalid.
+ */
+export function assertUniformName(name) {
+    if (!IDENTIFIER_PATTERN.test(name)) {
+        throw new Error(`Invalid uniform name: ${name}`);
+    }
+}
+/**
+ * Infers the WGSL type tag from a runtime uniform value.
+ *
+ * @param value - Uniform input value.
+ * @returns Inferred uniform type.
+ * @throws {Error} When the value does not match any supported shape.
+ */
+export function inferUniformType(value) {
+    if (isTypedUniformValue(value)) {
+        return value.type;
+    }
+    if (typeof value === 'number') {
+        return 'f32';
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 2) {
+            return 'vec2f';
+        }
+        if (value.length === 3) {
+            return 'vec3f';
+        }
+        if (value.length === 4) {
+            return 'vec4f';
+        }
+    }
+    throw new Error('Uniform value must resolve to f32, vec2f, vec3f, vec4f or mat4x4f');
+}
+/**
+ * Validates that a uniform value matches an explicit uniform type declaration.
+ *
+ * @param type - Declared WGSL type.
+ * @param value - Runtime value to validate.
+ * @throws {Error} When the value shape is incompatible with the declared type.
+ */
+export function assertUniformValueForType(type, value) {
+    const input = isTypedUniformValue(value) ? value.value : value;
+    if (type === 'f32') {
+        if (typeof input !== 'number' || !Number.isFinite(input)) {
+            throw new Error('Uniform f32 value must be a finite number');
+        }
+        return;
+    }
+    if (type === 'vec2f') {
+        if (!isTuple(input, 2)) {
+            throw new Error('Uniform vec2f value must be a tuple with 2 numbers');
+        }
+        return;
+    }
+    if (type === 'vec3f') {
+        if (!isTuple(input, 3)) {
+            throw new Error('Uniform vec3f value must be a tuple with 3 numbers');
+        }
+        return;
+    }
+    if (type === 'vec4f') {
+        if (!isTuple(input, 4)) {
+            throw new Error('Uniform vec4f value must be a tuple with 4 numbers');
+        }
+        return;
+    }
+    if (!isMat4Value(input)) {
+        throw new Error('Uniform mat4x4f value must contain 16 numbers');
+    }
+}
+/**
+ * Resolves a deterministic packed uniform buffer layout from a uniform map.
+ *
+ * @param uniforms - Input uniform definitions.
+ * @returns Sorted layout with byte offsets and final buffer byte length.
+ */
+export function resolveUniformLayout(uniforms) {
+    const names = Object.keys(uniforms).sort();
+    let offset = 0;
+    const entries = [];
+    const byName = {};
+    for (const name of names) {
+        assertUniformName(name);
+        const type = inferUniformType(uniforms[name]);
+        const { alignment, size } = getTypeLayout(type);
+        offset = roundUp(offset, alignment);
+        const entry = {
+            name,
+            type,
+            offset,
+            size
+        };
+        entries.push(entry);
+        byName[name] = entry;
+        offset += size;
+    }
+    const byteLength = Math.max(16, roundUp(offset, 16));
+    return { entries, byName, byteLength };
+}
+/**
+ * Writes one validated uniform value directly into the output float buffer.
+ */
+function writeUniformValue(type, value, data, base) {
+    const input = isTypedUniformValue(value) ? value.value : value;
+    assertUniformValueForType(type, value);
+    if (type === 'f32') {
+        data[base] = input;
+        return;
+    }
+    if (type === 'mat4x4f') {
+        const matrix = input;
+        if (matrix instanceof Float32Array) {
+            for (let index = 0; index < 16; index += 1) {
+                data[base + index] = matrix[index] ?? 0;
+            }
+            return;
+        }
+        for (let index = 0; index < 16; index += 1) {
+            data[base + index] = matrix[index] ?? 0;
+        }
+        return;
+    }
+    const tuple = input;
+    const length = type === 'vec2f' ? 2 : type === 'vec3f' ? 3 : 4;
+    for (let index = 0; index < length; index += 1) {
+        data[base + index] = tuple[index] ?? 0;
+    }
+}
+/**
+ * Packs uniforms into a newly allocated `Float32Array`.
+ *
+ * @param uniforms - Uniform values to pack.
+ * @param layout - Target layout definition.
+ * @returns Packed float buffer sized to `layout.byteLength`.
+ */
+export function packUniforms(uniforms, layout) {
+    const data = new Float32Array(layout.byteLength / 4);
+    packUniformsInto(uniforms, layout, data);
+    return data;
+}
+/**
+ * Packs uniforms into an existing output buffer and zeroes missing values.
+ *
+ * @param uniforms - Uniform values to pack.
+ * @param layout - Target layout metadata.
+ * @param data - Destination float buffer.
+ * @throws {Error} When `data` size does not match the required layout size.
+ */
+export function packUniformsInto(uniforms, layout, data) {
+    const requiredLength = layout.byteLength / 4;
+    if (data.length !== requiredLength) {
+        throw new Error(`Uniform output buffer size mismatch. Expected ${requiredLength}, got ${data.length}`);
+    }
+    data.fill(0);
+    for (const entry of layout.entries) {
+        const raw = uniforms[entry.name];
+        if (raw === undefined) {
+            continue;
+        }
+        const base = entry.offset / 4;
+        writeUniformValue(entry.type, raw, data, base);
+    }
+}

package/dist/current-writable.d.ts

@@ -0,0 +1,31 @@
+import { type Readable } from 'svelte/store';
+/**
+ * Readable store with synchronous access to the latest value.
+ */
+export interface CurrentReadable<T> extends Readable<T> {
+    /**
+     * Latest store value.
+     */
+    readonly current: T;
+}
+/**
+ * Writable extension of {@link CurrentReadable}.
+ */
+export interface CurrentWritable<T> extends CurrentReadable<T> {
+    /**
+     * Sets next value.
+     */
+    set: (value: T) => void;
+    /**
+     * Updates value based on previous value.
+     */
+    update: (updater: (value: T) => T) => void;
+}
+/**
+ * Creates a writable store that exposes the current value without subscription.
+ *
+ * @param initialValue - Initial store value.
+ * @param onChange - Optional side-effect callback invoked on every `set`.
+ * @returns Current-aware writable store.
+ */
+export declare function currentWritable<T>(initialValue: T, onChange?: (value: T) => void): CurrentWritable<T>;

package/dist/current-writable.js

@@ -0,0 +1,27 @@
+import { writable } from 'svelte/store';
+/**
+ * Creates a writable store that exposes the current value without subscription.
+ *
+ * @param initialValue - Initial store value.
+ * @param onChange - Optional side-effect callback invoked on every `set`.
+ * @returns Current-aware writable store.
+ */
+export function currentWritable(initialValue, onChange) {
+    let current = initialValue;
+    const store = writable(initialValue);
+    const set = (value) => {
+        current = value;
+        store.set(value);
+        onChange?.(value);
+    };
+    return {
+        get current() {
+            return current;
+        },
+        subscribe: store.subscribe,
+        set,
+        update(updater) {
+            set(updater(current));
+        }
+    };
+}

package/dist/frame-context.d.ts

@@ -0,0 +1,287 @@
+import { type Readable } from 'svelte/store';
+import type { FrameInvalidationToken, FrameState, RenderMode } from './core/types';
+/**
+ * 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: Readable<boolean>;
+}
+/**
+ * Snapshot of the resolved stage/task execution order.
+ */
+export interface FrameScheduleSnapshot {
+    stages: Array<{
+        key: string;
+        tasks: string[];
+    }>;
+}
+/**
+ * Optional scheduler diagnostics payload captured for the last run.
+ */
+export interface FrameRunTimings {
+    total: number;
+    stages: Record<string, {
+        duration: number;
+        tasks: Record<string, number>;
+    }>;
+}
+/**
+ * Aggregated timing statistics for stage/task profiling.
+ */
+export interface FrameTimingStats {
+    last: number;
+    avg: number;
+    min: number;
+    max: number;
+    count: number;
+}
+/**
+ * Profiling snapshot aggregated from the configured history window.
+ */
+export interface FrameProfilingSnapshot {
+    window: number;
+    frameCount: number;
+    lastFrame: FrameRunTimings | null;
+    total: FrameTimingStats;
+    stages: Record<string, {
+        timings: FrameTimingStats;
+        tasks: Record<string, FrameTimingStats>;
+    }>;
+}
+/**
+ * Internal registration payload including unsubscribe callback.
+ */
+interface RegisteredFrameTask extends UseFrameResult {
+    unsubscribe: () => void;
+}
+/**
+ * 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 (in 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 (in 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;
+/**
+ * Provides a frame registry through Svelte context.
+ *
+ * @param registry - Registry to provide.
+ */
+export declare function provideFrameRegistry(registry: FrameRegistry): void;
+/**
+ * Registers a frame callback using an auto-generated task key.
+ */
+export declare function useFrame(callback: FrameCallback, options?: UseFrameOptions): UseFrameResult;
+/**
+ * Registers a frame callback with an explicit task key.
+ */
+export declare function useFrame(key: FrameKey, callback: FrameCallback, options?: UseFrameOptions): UseFrameResult;
+export {};