@motion-core/motion-gpu 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public MotionGPU package entrypoint.
+ *
+ * Exposes the production-ready core API for fullscreen WGSL rendering workflows.
+ */
+export { default as FragCanvas } from './FragCanvas.svelte';
+export { defineMaterial } from './core/material';
+export { BlitPass, CopyPass, ShaderPass } from './passes';
+export { useMotionGPU } from './motiongpu-context';
+export { useFrame } from './frame-context';
+export { useTexture } from './use-texture';
+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';
+export type { LoadedTexture, TextureDecodeOptions, TextureLoadOptions } from './core/texture-loader';
+export type { FragMaterial, FragMaterialInput, MaterialIncludes, MaterialDefineValue, MaterialDefines, TypedMaterialDefineValue } from './core/material';
+export type { MotionGPUContext } from './motiongpu-context';
+export type { UseFrameOptions, UseFrameResult } from './frame-context';
+export type { TextureUrlInput, UseTextureResult } from './use-texture';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Public MotionGPU package entrypoint.
+ *
+ * Exposes the production-ready core API for fullscreen WGSL rendering workflows.
+ */
+export { default as FragCanvas } from './FragCanvas.svelte';
+export { defineMaterial } from './core/material';
+export { BlitPass, CopyPass, ShaderPass } from './passes';
+export { useMotionGPU } from './motiongpu-context';
+export { useFrame } from './frame-context';
+export { useTexture } from './use-texture';

package/dist/motiongpu-context.d.ts

@@ -0,0 +1,77 @@
+import type { RenderMode } from './core/types';
+import type { CurrentReadable, CurrentWritable } from './current-writable';
+import type { FrameProfilingSnapshot, FrameRegistry, FrameRunTimings, FrameScheduleSnapshot } from './frame-context';
+/**
+ * Exposed subset of frame scheduler controls intended for public consumption.
+ */
+export type MotionGPUScheduler = Pick<FrameRegistry, 'createStage' | 'getStage' | 'setDiagnosticsEnabled' | 'getDiagnosticsEnabled' | 'getLastRunTimings' | 'getSchedule' | 'setProfilingEnabled' | 'setProfilingWindow' | 'resetProfiling' | 'getProfilingEnabled' | 'getProfilingWindow' | 'getProfilingSnapshot'>;
+export type { FrameProfilingSnapshot, FrameRunTimings, FrameScheduleSnapshot };
+/**
+ * Namespace identifier for user-owned context entries.
+ */
+export type MotionGPUUserNamespace = string | symbol;
+/**
+ * Shared user context store exposed by `FragCanvas`.
+ */
+export type MotionGPUUserContext = CurrentWritable<Record<MotionGPUUserNamespace, unknown>>;
+/**
+ * Public `FragCanvas` runtime context available to hooks and user components.
+ */
+export interface MotionGPUContext {
+    /**
+     * Underlying canvas element used by the renderer.
+     */
+    canvas: HTMLCanvasElement | undefined;
+    /**
+     * Reactive canvas pixel size.
+     */
+    size: CurrentReadable<{
+        width: number;
+        height: number;
+    }>;
+    /**
+     * Device pixel ratio multiplier.
+     */
+    dpr: CurrentWritable<number>;
+    /**
+     * Max frame delta clamp passed to scheduled callbacks.
+     */
+    maxDelta: CurrentWritable<number>;
+    /**
+     * Scheduler render mode (`always`, `on-demand`, `manual`).
+     */
+    renderMode: CurrentWritable<RenderMode>;
+    /**
+     * Global toggle for automatic rendering.
+     */
+    autoRender: CurrentWritable<boolean>;
+    /**
+     * Namespaced user context store shared within the canvas subtree.
+     */
+    user: MotionGPUUserContext;
+    /**
+     * Marks current frame as invalidated.
+     */
+    invalidate: () => void;
+    /**
+     * Requests one manual frame advance.
+     */
+    advance: () => void;
+    /**
+     * Public scheduler API.
+     */
+    scheduler: MotionGPUScheduler;
+}
+/**
+ * Registers the motiongpu context in the current Svelte component tree.
+ *
+ * @param context - Context payload to provide.
+ */
+export declare function provideMotionGPUContext(context: MotionGPUContext): void;
+/**
+ * Returns the active motiongpu context.
+ *
+ * @returns Active context.
+ * @throws {Error} When called outside `<FragCanvas>`.
+ */
+export declare function useMotionGPU(): MotionGPUContext;

package/dist/motiongpu-context.js

@@ -0,0 +1,26 @@
+import { getContext, setContext } from 'svelte';
+/**
+ * Svelte context key used to expose `FragCanvas` runtime state.
+ */
+const MOTIONGPU_CONTEXT_KEY = Symbol('motiongpu.context');
+/**
+ * Registers the motiongpu context in the current Svelte component tree.
+ *
+ * @param context - Context payload to provide.
+ */
+export function provideMotionGPUContext(context) {
+    setContext(MOTIONGPU_CONTEXT_KEY, context);
+}
+/**
+ * Returns the active motiongpu context.
+ *
+ * @returns Active context.
+ * @throws {Error} When called outside `<FragCanvas>`.
+ */
+export function useMotionGPU() {
+    const context = getContext(MOTIONGPU_CONTEXT_KEY);
+    if (!context) {
+        throw new Error('useMotionGPU must be used inside <FragCanvas>');
+    }
+    return context;
+}

package/dist/passes/BlitPass.d.ts

@@ -0,0 +1,32 @@
+import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types';
+export interface BlitPassOptions extends RenderPassFlags {
+    enabled?: boolean;
+    needsSwap?: boolean;
+    input?: RenderPassInputSlot;
+    output?: RenderPassOutputSlot;
+    filter?: GPUFilterMode;
+}
+/**
+ * Fullscreen texture blit pass.
+ */
+export declare class BlitPass implements RenderPass {
+    enabled: boolean;
+    needsSwap: boolean;
+    input: RenderPassInputSlot;
+    output: RenderPassOutputSlot;
+    clear: boolean;
+    clearColor: [number, number, number, number];
+    preserve: boolean;
+    private readonly filter;
+    private device;
+    private sampler;
+    private bindGroupLayout;
+    private shaderModule;
+    private readonly pipelineByFormat;
+    private bindGroupByView;
+    constructor(options?: BlitPassOptions);
+    private ensureResources;
+    setSize(width: number, height: number): void;
+    render(context: RenderPassContext): void;
+    dispose(): void;
+}

package/dist/passes/BlitPass.js

@@ -0,0 +1,158 @@
+const FULLSCREEN_BLIT_SHADER = `
+struct MotionGPUVertexOut {
+	@builtin(position) position: vec4f,
+	@location(0) uv: vec2f,
+};
+
+@group(0) @binding(0) var motiongpuBlitSampler: sampler;
+@group(0) @binding(1) var motiongpuBlitTexture: texture_2d<f32>;
+
+@vertex
+fn motiongpuBlitVertex(@builtin(vertex_index) index: u32) -> MotionGPUVertexOut {
+	var positions = array<vec2f, 3>(
+		vec2f(-1.0, -3.0),
+		vec2f(-1.0, 1.0),
+		vec2f(3.0, 1.0)
+	);
+
+	let position = positions[index];
+	var out: MotionGPUVertexOut;
+	out.position = vec4f(position, 0.0, 1.0);
+	out.uv = (position + vec2f(1.0, 1.0)) * 0.5;
+	return out;
+}
+
+@fragment
+fn motiongpuBlitFragment(in: MotionGPUVertexOut) -> @location(0) vec4f {
+	return textureSample(motiongpuBlitTexture, motiongpuBlitSampler, in.uv);
+}
+`;
+/**
+ * Fullscreen texture blit pass.
+ */
+export class BlitPass {
+    enabled;
+    needsSwap;
+    input;
+    output;
+    clear;
+    clearColor;
+    preserve;
+    filter;
+    device = null;
+    sampler = null;
+    bindGroupLayout = null;
+    shaderModule = null;
+    pipelineByFormat = new Map();
+    bindGroupByView = new WeakMap();
+    constructor(options = {}) {
+        this.enabled = options.enabled ?? true;
+        this.needsSwap = options.needsSwap ?? true;
+        this.input = options.input ?? 'source';
+        this.output = options.output ?? (this.needsSwap ? 'target' : 'source');
+        this.clear = options.clear ?? false;
+        this.clearColor = options.clearColor ?? [0, 0, 0, 1];
+        this.preserve = options.preserve ?? true;
+        this.filter = options.filter ?? 'linear';
+    }
+    ensureResources(device, format) {
+        if (this.device !== device) {
+            this.device = device;
+            this.sampler = null;
+            this.bindGroupLayout = null;
+            this.shaderModule = null;
+            this.pipelineByFormat.clear();
+            this.bindGroupByView = new WeakMap();
+        }
+        if (!this.sampler) {
+            this.sampler = device.createSampler({
+                magFilter: this.filter,
+                minFilter: this.filter,
+                addressModeU: 'clamp-to-edge',
+                addressModeV: 'clamp-to-edge'
+            });
+        }
+        if (!this.bindGroupLayout) {
+            this.bindGroupLayout = device.createBindGroupLayout({
+                entries: [
+                    {
+                        binding: 0,
+                        visibility: GPUShaderStage.FRAGMENT,
+                        sampler: { type: 'filtering' }
+                    },
+                    {
+                        binding: 1,
+                        visibility: GPUShaderStage.FRAGMENT,
+                        texture: {
+                            sampleType: 'float',
+                            viewDimension: '2d',
+                            multisampled: false
+                        }
+                    }
+                ]
+            });
+        }
+        if (!this.shaderModule) {
+            this.shaderModule = device.createShaderModule({
+                code: FULLSCREEN_BLIT_SHADER
+            });
+        }
+        let pipeline = this.pipelineByFormat.get(format);
+        if (!pipeline) {
+            const pipelineLayout = device.createPipelineLayout({
+                bindGroupLayouts: [this.bindGroupLayout]
+            });
+            pipeline = device.createRenderPipeline({
+                layout: pipelineLayout,
+                vertex: {
+                    module: this.shaderModule,
+                    entryPoint: 'motiongpuBlitVertex'
+                },
+                fragment: {
+                    module: this.shaderModule,
+                    entryPoint: 'motiongpuBlitFragment',
+                    targets: [{ format }]
+                },
+                primitive: { topology: 'triangle-list' }
+            });
+            this.pipelineByFormat.set(format, pipeline);
+        }
+        return {
+            sampler: this.sampler,
+            bindGroupLayout: this.bindGroupLayout,
+            pipeline
+        };
+    }
+    setSize(width, height) {
+        void width;
+        void height;
+    }
+    render(context) {
+        const { sampler, bindGroupLayout, pipeline } = this.ensureResources(context.device, context.output.format);
+        const inputView = context.input.view;
+        let bindGroup = this.bindGroupByView.get(inputView);
+        if (!bindGroup) {
+            bindGroup = context.device.createBindGroup({
+                layout: bindGroupLayout,
+                entries: [
+                    { binding: 0, resource: sampler },
+                    { binding: 1, resource: inputView }
+                ]
+            });
+            this.bindGroupByView.set(inputView, bindGroup);
+        }
+        const pass = context.beginRenderPass();
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.draw(3);
+        pass.end();
+    }
+    dispose() {
+        this.device = null;
+        this.sampler = null;
+        this.bindGroupLayout = null;
+        this.shaderModule = null;
+        this.pipelineByFormat.clear();
+        this.bindGroupByView = new WeakMap();
+    }
+}

package/dist/passes/CopyPass.d.ts

@@ -0,0 +1,25 @@
+import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types';
+export interface CopyPassOptions extends RenderPassFlags {
+    enabled?: boolean;
+    needsSwap?: boolean;
+    input?: RenderPassInputSlot;
+    output?: RenderPassOutputSlot;
+    filter?: GPUFilterMode;
+}
+/**
+ * Texture copy pass with fullscreen-blit fallback.
+ */
+export declare class CopyPass implements RenderPass {
+    enabled: boolean;
+    needsSwap: boolean;
+    input: RenderPassInputSlot;
+    output: RenderPassOutputSlot;
+    clear: boolean;
+    clearColor: [number, number, number, number];
+    preserve: boolean;
+    private readonly fallbackBlit;
+    constructor(options?: CopyPassOptions);
+    setSize(width: number, height: number): void;
+    render(context: RenderPassContext): void;
+    dispose(): void;
+}

package/dist/passes/CopyPass.js

@@ -0,0 +1,53 @@
+import { BlitPass } from './BlitPass';
+/**
+ * Texture copy pass with fullscreen-blit fallback.
+ */
+export class CopyPass {
+    enabled;
+    needsSwap;
+    input;
+    output;
+    clear;
+    clearColor;
+    preserve;
+    fallbackBlit;
+    constructor(options = {}) {
+        this.enabled = options.enabled ?? true;
+        this.needsSwap = options.needsSwap ?? true;
+        this.input = options.input ?? 'source';
+        this.output = options.output ?? (this.needsSwap ? 'target' : 'source');
+        this.clear = options.clear ?? false;
+        this.clearColor = options.clearColor ?? [0, 0, 0, 1];
+        this.preserve = options.preserve ?? true;
+        this.fallbackBlit = new BlitPass({
+            enabled: true,
+            needsSwap: false,
+            input: this.input,
+            output: this.output,
+            ...(options.filter !== undefined ? { filter: options.filter } : {})
+        });
+    }
+    setSize(width, height) {
+        this.fallbackBlit.setSize(width, height);
+    }
+    render(context) {
+        const source = context.input;
+        const target = context.output;
+        const canDirectCopy = context.clear === false &&
+            context.preserve === true &&
+            source.texture !== target.texture &&
+            source.texture !== context.canvas.texture &&
+            target.texture !== context.canvas.texture &&
+            source.width === target.width &&
+            source.height === target.height &&
+            source.format === target.format;
+        if (canDirectCopy) {
+            context.commandEncoder.copyTextureToTexture({ texture: source.texture }, { texture: target.texture }, { width: source.width, height: source.height, depthOrArrayLayers: 1 });
+            return;
+        }
+        this.fallbackBlit.render(context);
+    }
+    dispose() {
+        this.fallbackBlit.dispose();
+    }
+}

package/dist/passes/ShaderPass.d.ts

@@ -0,0 +1,40 @@
+import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types';
+export interface ShaderPassOptions extends RenderPassFlags {
+    fragment: string;
+    enabled?: boolean;
+    needsSwap?: boolean;
+    input?: RenderPassInputSlot;
+    output?: RenderPassOutputSlot;
+    filter?: GPUFilterMode;
+}
+/**
+ * Fullscreen programmable shader pass.
+ */
+export declare class ShaderPass implements RenderPass {
+    enabled: boolean;
+    needsSwap: boolean;
+    input: RenderPassInputSlot;
+    output: RenderPassOutputSlot;
+    clear: boolean;
+    clearColor: [number, number, number, number];
+    preserve: boolean;
+    private readonly filter;
+    private fragment;
+    private program;
+    private device;
+    private sampler;
+    private bindGroupLayout;
+    private shaderModule;
+    private readonly pipelineByFormat;
+    private bindGroupByView;
+    constructor(options: ShaderPassOptions);
+    /**
+     * Replaces current shader fragment and invalidates pipeline cache.
+     */
+    setFragment(fragment: string): void;
+    getFragment(): string;
+    private ensureResources;
+    setSize(width: number, height: number): void;
+    render(context: RenderPassContext): void;
+    dispose(): void;
+}

package/dist/passes/ShaderPass.js

@@ -0,0 +1,182 @@
+const SHADER_PASS_CONTRACT = /\bfn\s+shade\s*\(\s*inputColor\s*:\s*vec4f\s*,\s*uv\s*:\s*vec2f\s*\)\s*->\s*vec4f/;
+function buildShaderPassProgram(fragment) {
+    if (!SHADER_PASS_CONTRACT.test(fragment)) {
+        throw new Error('ShaderPass fragment must declare `fn shade(inputColor: vec4f, uv: vec2f) -> vec4f`.');
+    }
+    return `
+struct MotionGPUVertexOut {
+	@builtin(position) position: vec4f,
+	@location(0) uv: vec2f,
+};
+
+@group(0) @binding(0) var motiongpuShaderPassSampler: sampler;
+@group(0) @binding(1) var motiongpuShaderPassTexture: texture_2d<f32>;
+
+@vertex
+fn motiongpuShaderPassVertex(@builtin(vertex_index) index: u32) -> MotionGPUVertexOut {
+	var positions = array<vec2f, 3>(
+		vec2f(-1.0, -3.0),
+		vec2f(-1.0, 1.0),
+		vec2f(3.0, 1.0)
+	);
+
+	let position = positions[index];
+	var out: MotionGPUVertexOut;
+	out.position = vec4f(position, 0.0, 1.0);
+	out.uv = (position + vec2f(1.0, 1.0)) * 0.5;
+	return out;
+}
+
+${fragment}
+
+@fragment
+fn motiongpuShaderPassFragment(in: MotionGPUVertexOut) -> @location(0) vec4f {
+	let inputColor = textureSample(motiongpuShaderPassTexture, motiongpuShaderPassSampler, in.uv);
+	return shade(inputColor, in.uv);
+}
+`;
+}
+/**
+ * Fullscreen programmable shader pass.
+ */
+export class ShaderPass {
+    enabled;
+    needsSwap;
+    input;
+    output;
+    clear;
+    clearColor;
+    preserve;
+    filter;
+    fragment;
+    program;
+    device = null;
+    sampler = null;
+    bindGroupLayout = null;
+    shaderModule = null;
+    pipelineByFormat = new Map();
+    bindGroupByView = new WeakMap();
+    constructor(options) {
+        this.enabled = options.enabled ?? true;
+        this.needsSwap = options.needsSwap ?? true;
+        this.input = options.input ?? 'source';
+        this.output = options.output ?? (this.needsSwap ? 'target' : 'source');
+        this.clear = options.clear ?? false;
+        this.clearColor = options.clearColor ?? [0, 0, 0, 1];
+        this.preserve = options.preserve ?? true;
+        this.filter = options.filter ?? 'linear';
+        this.fragment = options.fragment;
+        this.program = buildShaderPassProgram(options.fragment);
+    }
+    /**
+     * Replaces current shader fragment and invalidates pipeline cache.
+     */
+    setFragment(fragment) {
+        this.fragment = fragment;
+        this.program = buildShaderPassProgram(fragment);
+        this.shaderModule = null;
+        this.pipelineByFormat.clear();
+        this.bindGroupByView = new WeakMap();
+    }
+    getFragment() {
+        return this.fragment;
+    }
+    ensureResources(device, format) {
+        if (this.device !== device) {
+            this.device = device;
+            this.sampler = null;
+            this.bindGroupLayout = null;
+            this.shaderModule = null;
+            this.pipelineByFormat.clear();
+            this.bindGroupByView = new WeakMap();
+        }
+        if (!this.sampler) {
+            this.sampler = device.createSampler({
+                magFilter: this.filter,
+                minFilter: this.filter,
+                addressModeU: 'clamp-to-edge',
+                addressModeV: 'clamp-to-edge'
+            });
+        }
+        if (!this.bindGroupLayout) {
+            this.bindGroupLayout = device.createBindGroupLayout({
+                entries: [
+                    {
+                        binding: 0,
+                        visibility: GPUShaderStage.FRAGMENT,
+                        sampler: { type: 'filtering' }
+                    },
+                    {
+                        binding: 1,
+                        visibility: GPUShaderStage.FRAGMENT,
+                        texture: {
+                            sampleType: 'float',
+                            viewDimension: '2d',
+                            multisampled: false
+                        }
+                    }
+                ]
+            });
+        }
+        if (!this.shaderModule) {
+            this.shaderModule = device.createShaderModule({ code: this.program });
+        }
+        let pipeline = this.pipelineByFormat.get(format);
+        if (!pipeline) {
+            const pipelineLayout = device.createPipelineLayout({
+                bindGroupLayouts: [this.bindGroupLayout]
+            });
+            pipeline = device.createRenderPipeline({
+                layout: pipelineLayout,
+                vertex: {
+                    module: this.shaderModule,
+                    entryPoint: 'motiongpuShaderPassVertex'
+                },
+                fragment: {
+                    module: this.shaderModule,
+                    entryPoint: 'motiongpuShaderPassFragment',
+                    targets: [{ format }]
+                },
+                primitive: { topology: 'triangle-list' }
+            });
+            this.pipelineByFormat.set(format, pipeline);
+        }
+        return {
+            sampler: this.sampler,
+            bindGroupLayout: this.bindGroupLayout,
+            pipeline
+        };
+    }
+    setSize(width, height) {
+        void width;
+        void height;
+    }
+    render(context) {
+        const { sampler, bindGroupLayout, pipeline } = this.ensureResources(context.device, context.output.format);
+        const inputView = context.input.view;
+        let bindGroup = this.bindGroupByView.get(inputView);
+        if (!bindGroup) {
+            bindGroup = context.device.createBindGroup({
+                layout: bindGroupLayout,
+                entries: [
+                    { binding: 0, resource: sampler },
+                    { binding: 1, resource: inputView }
+                ]
+            });
+            this.bindGroupByView.set(inputView, bindGroup);
+        }
+        const pass = context.beginRenderPass();
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.draw(3);
+        pass.end();
+    }
+    dispose() {
+        this.device = null;
+        this.sampler = null;
+        this.bindGroupLayout = null;
+        this.shaderModule = null;
+        this.pipelineByFormat.clear();
+        this.bindGroupByView = new WeakMap();
+    }
+}

package/dist/passes/index.d.ts

@@ -0,0 +1,3 @@
+export { BlitPass, type BlitPassOptions } from './BlitPass';
+export { CopyPass, type CopyPassOptions } from './CopyPass';
+export { ShaderPass, type ShaderPassOptions } from './ShaderPass';

package/dist/passes/index.js

@@ -0,0 +1,3 @@
+export { BlitPass } from './BlitPass';
+export { CopyPass } from './CopyPass';
+export { ShaderPass } from './ShaderPass';

package/dist/use-motiongpu-user-context.d.ts

@@ -0,0 +1,35 @@
+import type { CurrentReadable } from './current-writable';
+import { type MotionGPUUserNamespace } from './motiongpu-context';
+/**
+ * Internal shape of the user context store.
+ */
+type UserContextStore = Record<MotionGPUUserNamespace, unknown>;
+/**
+ * Controls how a namespaced user context value behaves when already present.
+ */
+export interface SetMotionGPUUserContextOptions {
+    /**
+     * Conflict strategy when namespace already exists:
+     * - `skip`: keep current value
+     * - `replace`: replace current value
+     * - `merge`: shallow merge object values, fallback to replace otherwise
+     *
+     * @default 'skip'
+     */
+    existing?: 'merge' | 'replace' | 'skip';
+}
+/**
+ * Returns a read-only view of the entire motiongpu user context store.
+ */
+export declare function useMotionGPUUserContext<UC extends UserContextStore = UserContextStore>(): CurrentReadable<UC>;
+/**
+ * Reads a namespaced user context value as a reactive readable store.
+ */
+export declare function useMotionGPUUserContext<UCT = unknown>(namespace: MotionGPUUserNamespace): CurrentReadable<UCT | undefined>;
+/**
+ * Sets a namespaced user context value with explicit write semantics.
+ *
+ * Returns the effective value stored under the namespace.
+ */
+export declare function setMotionGPUUserContext<UCT = unknown>(namespace: MotionGPUUserNamespace, value: UCT | (() => UCT), options?: SetMotionGPUUserContextOptions): UCT | undefined;
+export {};