@motion-core/motion-gpu 0.1.0 → 0.2.0

package/README.md

@@ -12,8 +12,8 @@
 
 **A tiny WebGPU runtime for writing Shadertoy-style fullscreen shaders in pure WGSL.**
 
-`@motion-core/motion-gpu` is a Svelte 5 package for building fullscreen shader pipelines using WebGPU and WGSL.
-It provides a minimal runtime, scheduler, and render graph designed specifically for fragment-driven GPU programs.
+`@motion-core/motion-gpu` ships a framework-agnostic core plus a Svelte 5 adapter for building fullscreen shader pipelines using WebGPU and WGSL.
+It provides a minimal runtime loop, scheduler, and render graph designed specifically for fragment-driven GPU programs.
 
 Unlike general-purpose 3D engines, Motion GPU focuses on a very narrow problem: **running fullscreen fragment shaders and multi-pass GPU pipelines**.
 
@@ -87,9 +87,9 @@ Motion GPU follows a simple three-step flow:
 
 # Entrypoints
 
-## Root (`@motion-core/motion-gpu`)
+## Svelte adapter
 
-Primary runtime API:
+`@motion-core/motion-gpu/svelte` exposes the runtime API for Svelte:
 
 - `FragCanvas`
 - `defineMaterial`
@@ -110,9 +110,7 @@ Also exports runtime/core types:
 
 ---
 
-## Advanced (`@motion-core/motion-gpu/advanced`)
-
-Re-exports everything from root, plus:
+`@motion-core/motion-gpu/svelte/advanced` re-exports everything above, plus:
 
 - `useMotionGPUUserContext`
 - `setMotionGPUUserContext`
@@ -121,9 +119,31 @@ Re-exports everything from root, plus:
 
 ---
 
+## Framework-agnostic core
+
+`@motion-core/motion-gpu` (and explicit alias `@motion-core/motion-gpu/core`) exposes adapter-building primitives:
+
+- `defineMaterial`
+- `resolveMaterial`
+- `createCurrentWritable`
+- `createFrameRegistry`
+- `createMotionGPURuntimeLoop`
+- `loadTexturesFromUrls`
+- `toMotionGPUErrorReport`
+- `ShaderPass`
+- `BlitPass`
+- `CopyPass`
+
+`@motion-core/motion-gpu/advanced` (and explicit alias `@motion-core/motion-gpu/core/advanced`) re-exports core plus:
+
+- `applySchedulerPreset`
+- `captureSchedulerDebugSnapshot`
+
+---
+
 # Requirements
 
-- Svelte 5 (`peerDependency: svelte ^5`)
+- Svelte 5 is required only for the Svelte adapter entrypoints (`/svelte`, `/svelte/advanced`)
 - A browser/runtime with WebGPU support
 - Secure context (`https://` or `localhost`)
 
@@ -144,7 +164,7 @@ npm i @motion-core/motion-gpu
 ```svelte
 <!-- App.svelte -->
 <script lang="ts">
-	import { FragCanvas, defineMaterial } from '@motion-core/motion-gpu';
+	import { FragCanvas, defineMaterial } from '@motion-core/motion-gpu/svelte';
 
 	const material = defineMaterial({
 		fragment: `
@@ -167,7 +187,7 @@ fn frag(uv: vec2f) -> vec4f {
 ```svelte
 <!-- App.svelte -->
 <script lang="ts">
-	import { FragCanvas, defineMaterial } from '@motion-core/motion-gpu';
+	import { FragCanvas, defineMaterial } from '@motion-core/motion-gpu/svelte';
 	import Runtime from './Runtime.svelte';
 
 	const material = defineMaterial({
@@ -191,7 +211,7 @@ fn frag(uv: vec2f) -> vec4f {
 ```svelte
 <!-- Runtime.svelte -->
 <script lang="ts">
-	import { useFrame } from '@motion-core/motion-gpu';
+	import { useFrame } from '@motion-core/motion-gpu/svelte';
 
 	useFrame((state) => {
 		state.setUniform('uTime', state.time);

package/dist/advanced.d.ts

@@ -1,14 +1,6 @@
 /**
- * Advanced MotionGPU entrypoint.
+ * Root advanced package entrypoint.
  *
- * Includes power-user hooks and diagnostics-oriented types that are not part of the
- * minimal root API surface.
+ * Framework-agnostic advanced core entrypoint.
  */
-export * from './index';
-export { applySchedulerPreset, captureSchedulerDebugSnapshot } from './advanced-scheduler';
-export { setMotionGPUUserContext, useMotionGPUUserContext } from './use-motiongpu-user-context';
-export type { ApplySchedulerPresetOptions, SchedulerDebugSnapshot, SchedulerPreset, SchedulerPresetConfig } from './advanced-scheduler';
-export type { MotionGPUUserContext, MotionGPUUserNamespace } from './motiongpu-context';
-export type { FrameProfilingSnapshot, FrameKey, FrameTaskInvalidation, FrameTaskInvalidationToken, FrameRunTimings, FrameScheduleSnapshot, FrameStage, FrameStageCallback, FrameTimingStats, FrameTask } from './frame-context';
-export type { SetMotionGPUUserContextOptions } from './use-motiongpu-user-context';
-export type { RenderPassContext, RenderTarget, UniformLayout, UniformLayoutEntry } from './core/types';
+export * from './core/advanced.js';

package/dist/advanced.js

@@ -1,9 +1,6 @@
 /**
- * Advanced MotionGPU entrypoint.
+ * Root advanced package entrypoint.
  *
- * Includes power-user hooks and diagnostics-oriented types that are not part of the
- * minimal root API surface.
+ * Framework-agnostic advanced core entrypoint.
  */
-export * from './index';
-export { applySchedulerPreset, captureSchedulerDebugSnapshot } from './advanced-scheduler';
-export { setMotionGPUUserContext, useMotionGPUUserContext } from './use-motiongpu-user-context';
+export * from './core/advanced.js';

package/dist/core/advanced.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Framework-agnostic advanced MotionGPU core entrypoint.
+ */
+export * from './index.js';
+export { applySchedulerPreset, captureSchedulerDebugSnapshot } from './scheduler-helpers.js';
+export type { ApplySchedulerPresetOptions, MotionGPUScheduler, SchedulerDebugSnapshot, SchedulerPreset, SchedulerPresetConfig } from './scheduler-helpers.js';

package/dist/core/advanced.js

@@ -0,0 +1,5 @@
+/**
+ * Framework-agnostic advanced MotionGPU core entrypoint.
+ */
+export * from './index.js';
+export { applySchedulerPreset, captureSchedulerDebugSnapshot } from './scheduler-helpers.js';

package/dist/core/current-value.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal subscribe contract used by MotionGPU core.
+ */
+export interface Subscribable<T> {
+    subscribe: (run: (value: T) => void) => () => void;
+}
+/**
+ * Readable value with synchronous access to the latest value.
+ */
+export interface CurrentReadable<T> extends Subscribable<T> {
+    readonly current: T;
+}
+/**
+ * Writable extension of {@link CurrentReadable}.
+ */
+export interface CurrentWritable<T> extends CurrentReadable<T> {
+    set: (value: T) => void;
+    update: (updater: (value: T) => T) => void;
+}
+/**
+ * Creates a writable value with immediate subscription semantics.
+ */
+export declare function createCurrentWritable<T>(initialValue: T, onChange?: (value: T) => void): CurrentWritable<T>;

package/dist/core/current-value.js

@@ -0,0 +1,33 @@
+/**
+ * Creates a writable value with immediate subscription semantics.
+ */
+export function createCurrentWritable(initialValue, onChange) {
+    let current = initialValue;
+    const subscribers = new Set();
+    const notify = (value) => {
+        for (const run of subscribers) {
+            run(value);
+        }
+    };
+    const set = (value) => {
+        current = value;
+        notify(value);
+        onChange?.(value);
+    };
+    return {
+        get current() {
+            return current;
+        },
+        subscribe(run) {
+            subscribers.add(run);
+            run(current);
+            return () => {
+                subscribers.delete(run);
+            };
+        },
+        set,
+        update(updater) {
+            set(updater(current));
+        }
+    };
+}

package/dist/core/error-diagnostics.d.ts

@@ -1,4 +1,4 @@
-import type { MaterialSourceLocation } from './material-preprocess';
+import type { MaterialSourceLocation } from './material-preprocess.js';
 /**
  * Source metadata for material declaration callsite.
  */

package/dist/core/error-report.js

@@ -1,5 +1,5 @@
-import { getShaderCompilationDiagnostics } from './error-diagnostics';
-import { formatShaderSourceLocation } from './shader';
+import { getShaderCompilationDiagnostics } from './error-diagnostics.js';
+import { formatShaderSourceLocation } from './shader.js';
 /**
  * Splits multi-line values into trimmed non-empty lines.
  */

package/dist/{frame-context.d.ts → core/frame-registry.d.ts}

@@ -1,5 +1,5 @@
-import { type Readable } from 'svelte/store';
-import type { FrameInvalidationToken, FrameState, RenderMode } from './core/types';
+import { type Subscribable } from './current-value.js';
+import type { FrameInvalidationToken, FrameState, RenderMode } from './types.js';
 /**
  * Per-frame callback executed by the frame scheduler.
  */
@@ -97,7 +97,7 @@ export interface UseFrameResult {
     /**
      * Readable flag representing effective running state.
      */
-    started: Readable<boolean>;
+    started: Subscribable<boolean>;
 }
 /**
  * Snapshot of the resolved stage/task execution order.
@@ -270,18 +270,4 @@ export declare function createFrameRegistry(options?: {
     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 {};

package/dist/{frame-context.js → core/frame-registry.js}

@@ -1,9 +1,4 @@
-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');
+import { createCurrentWritable } from './current-value.js';
 /**
  * Default stage key used when task stage is not explicitly specified.
  */
@@ -492,7 +487,7 @@ export function createFrameRegistry(options) {
                 ? toStageKey(taskOptions.stage)
                 : (inferredStage?.stage ?? MAIN_STAGE_KEY);
             const stage = ensureStage(stageKey);
-            const startedWritable = writable(taskOptions.autoStart ?? true);
+            const startedWritable = createCurrentWritable(taskOptions.autoStart ?? true);
             const internalTask = {
                 task: { key, stage: stage.key },
                 callback,
@@ -699,33 +694,3 @@ export function createFrameRegistry(options) {
         }
     };
 }
-/**
- * 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
-    };
-}

package/dist/core/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Framework-agnostic MotionGPU core entrypoint.
+ *
+ * This surface is intended for building framework adapters (Svelte/React/Vue).
+ */
+export { defineMaterial, resolveMaterial } from './material.js';
+export { toMotionGPUErrorReport } from './error-report.js';
+export { createCurrentWritable } from './current-value.js';
+export { createFrameRegistry } from './frame-registry.js';
+export { createMotionGPURuntimeLoop } from './runtime-loop.js';
+export { loadTexturesFromUrls } from './texture-loader.js';
+export { BlitPass, CopyPass, ShaderPass } from '../passes/index.js';
+export type { CurrentReadable, CurrentWritable, Subscribable } from './current-value.js';
+export type { MotionGPUErrorPhase, MotionGPUErrorReport, MotionGPUErrorSource, MotionGPUErrorSourceLine } from './error-report.js';
+export type { FrameCallback, FrameKey, FrameProfilingSnapshot, FrameRegistry, FrameRunTimings, FrameScheduleSnapshot, FrameStage, FrameStageCallback, FrameTask, FrameTaskInvalidation, FrameTaskInvalidationToken, FrameTimingStats, UseFrameOptions, UseFrameResult } from './frame-registry.js';
+export type { FragMaterial, FragMaterialInput, MaterialDefineValue, MaterialDefines, MaterialIncludes, ResolvedMaterial, TypedMaterialDefineValue } from './material.js';
+export type { MotionGPURuntimeLoop, MotionGPURuntimeLoopOptions } from './runtime-loop.js';
+export type { LoadedTexture, TextureDecodeOptions, TextureLoadOptions } from './texture-loader.js';
+export type { FrameInvalidationToken, FrameState, OutputColorSpace, RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot, RenderMode, RenderTarget, RenderTargetDefinition, RenderTargetDefinitionMap, TextureData, TextureDefinition, TextureDefinitionMap, TextureMap, TextureSource, TextureUpdateMode, TextureValue, TypedUniform, UniformLayout, UniformLayoutEntry, UniformMap, UniformMat4Value, UniformType, UniformValue } from './types.js';

package/dist/core/index.js

@@ -0,0 +1,12 @@
+/**
+ * Framework-agnostic MotionGPU core entrypoint.
+ *
+ * This surface is intended for building framework adapters (Svelte/React/Vue).
+ */
+export { defineMaterial, resolveMaterial } from './material.js';
+export { toMotionGPUErrorReport } from './error-report.js';
+export { createCurrentWritable } from './current-value.js';
+export { createFrameRegistry } from './frame-registry.js';
+export { createMotionGPURuntimeLoop } from './runtime-loop.js';
+export { loadTexturesFromUrls } from './texture-loader.js';
+export { BlitPass, CopyPass, ShaderPass } from '../passes/index.js';

package/dist/core/material-preprocess.d.ts

@@ -1,4 +1,4 @@
-import type { MaterialDefineValue, MaterialDefines, MaterialIncludes } from './material';
+import type { MaterialDefineValue, MaterialDefines, MaterialIncludes } from './material.js';
 /**
  * Source location metadata for one generated fragment line.
  */

package/dist/core/material-preprocess.js

@@ -1,4 +1,4 @@
-import { assertUniformName } from './uniforms';
+import { assertUniformName } from './uniforms.js';
 const INCLUDE_DIRECTIVE_PATTERN = /^\s*#include\s+<([A-Za-z_][A-Za-z0-9_]*)>\s*$/;
 function normalizeTypedDefine(name, define) {
     const value = define.value;

package/dist/core/material.d.ts

@@ -1,7 +1,7 @@
-import type { MaterialSourceMetadata } from './error-diagnostics';
-import { resolveUniformLayout } from './uniforms';
-import { type MaterialLineMap } from './material-preprocess';
-import type { TextureDefinitionMap, UniformMap } from './types';
+import type { MaterialSourceMetadata } from './error-diagnostics.js';
+import { resolveUniformLayout } from './uniforms.js';
+import { type MaterialLineMap } from './material-preprocess.js';
+import type { TextureDefinitionMap, UniformMap } from './types.js';
 /**
  * Typed compile-time define declaration.
  */

package/dist/core/material.js

@@ -1,6 +1,6 @@
-import { normalizeTextureDefinition } from './textures';
-import { assertUniformName, assertUniformValueForType, inferUniformType, resolveUniformLayout } from './uniforms';
-import { normalizeDefines, normalizeIncludes, preprocessMaterialFragment, toDefineLine } from './material-preprocess';
+import { normalizeTextureDefinition } from './textures.js';
+import { assertUniformName, assertUniformValueForType, inferUniformType, resolveUniformLayout } from './uniforms.js';
+import { normalizeDefines, normalizeIncludes, preprocessMaterialFragment, toDefineLine } from './material-preprocess.js';
 /**
  * Strict fragment contract used by MotionGPU.
  */

package/dist/core/recompile-policy.d.ts

@@ -1,4 +1,4 @@
-import type { OutputColorSpace } from './types';
+import type { OutputColorSpace } from './types.js';
 /**
  * Inputs that affect renderer pipeline compilation.
  */

package/dist/core/render-graph.d.ts

@@ -1,4 +1,4 @@
-import type { RenderPass, RenderPassInputSlot, RenderPassOutputSlot } from './types';
+import type { RenderPass, RenderPassInputSlot, RenderPassOutputSlot } from './types.js';
 /**
  * Resolved render-pass step with defaults applied.
  */

package/dist/core/render-targets.d.ts

@@ -1,4 +1,4 @@
-import type { RenderTargetDefinitionMap } from './types';
+import type { RenderTargetDefinitionMap } from './types.js';
 /**
  * Concrete render target configuration resolved for current canvas size.
  */

package/dist/core/render-targets.js

@@ -1,4 +1,4 @@
-import { assertUniformName } from './uniforms';
+import { assertUniformName } from './uniforms.js';
 /**
  * Asserts positive finite numeric input for render target options.
  */

package/dist/core/renderer.d.ts

@@ -1,4 +1,4 @@
-import type { Renderer, RendererOptions } from './types';
+import type { Renderer, RendererOptions } from './types.js';
 /**
  * Creates the WebGPU renderer used by `FragCanvas`.
  *

package/dist/core/renderer.js

@@ -1,9 +1,9 @@
-import { buildRenderTargetSignature, resolveRenderTargetDefinitions } from './render-targets';
-import { planRenderGraph } from './render-graph';
-import { buildShaderSourceWithMap, formatShaderSourceLocation } from './shader';
-import { attachShaderCompilationDiagnostics } from './error-diagnostics';
-import { getTextureMipLevelCount, normalizeTextureDefinitions, resolveTextureUpdateMode, resolveTextureSize, toTextureData } from './textures';
-import { packUniformsInto } from './uniforms';
+import { buildRenderTargetSignature, resolveRenderTargetDefinitions } from './render-targets.js';
+import { planRenderGraph } from './render-graph.js';
+import { buildShaderSourceWithMap, formatShaderSourceLocation } from './shader.js';
+import { attachShaderCompilationDiagnostics } from './error-diagnostics.js';
+import { getTextureMipLevelCount, normalizeTextureDefinitions, resolveTextureUpdateMode, resolveTextureSize, toTextureData } from './textures.js';
+import { packUniformsInto } from './uniforms.js';
 /**
  * Binding index for frame uniforms (`time`, `delta`, `resolution`).
  */

package/dist/core/runtime-loop.d.ts

@@ -0,0 +1,31 @@
+import type { CurrentReadable, CurrentWritable } from './current-value.js';
+import { type FragMaterial } from './material.js';
+import { type MotionGPUErrorReport } from './error-report.js';
+import type { FrameRegistry } from './frame-registry.js';
+import type { FrameInvalidationToken, OutputColorSpace, RenderPass, RenderTargetDefinitionMap } from './types.js';
+export interface MotionGPURuntimeLoopOptions {
+    canvas: HTMLCanvasElement;
+    registry: FrameRegistry;
+    size: CurrentWritable<{
+        width: number;
+        height: number;
+    }>;
+    dpr: CurrentReadable<number>;
+    maxDelta: CurrentReadable<number>;
+    getMaterial: () => FragMaterial;
+    getRenderTargets: () => RenderTargetDefinitionMap;
+    getPasses: () => RenderPass[];
+    getClearColor: () => [number, number, number, number];
+    getOutputColorSpace: () => OutputColorSpace;
+    getAdapterOptions: () => GPURequestAdapterOptions | undefined;
+    getDeviceDescriptor: () => GPUDeviceDescriptor | undefined;
+    getOnError: () => ((report: MotionGPUErrorReport) => void) | undefined;
+    reportError: (report: MotionGPUErrorReport | null) => void;
+}
+export interface MotionGPURuntimeLoop {
+    requestFrame: () => void;
+    invalidate: (token?: FrameInvalidationToken) => void;
+    advance: () => void;
+    destroy: () => void;
+}
+export declare function createMotionGPURuntimeLoop(options: MotionGPURuntimeLoopOptions): MotionGPURuntimeLoop;