Motion GPU

Advanced

Changelog

All notable changes to Motion Core will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

This page is auto-generated from CHANGELOG.md in the repository root.

Unreleased

0.8.4 - 2026-04-24

Changed

  • Material signatures now include texture allocation and runtime-update configuration (format, storage, update, width, and height) so renderer state is rebuilt when texture contracts change.
  • TextureDefinition.fragmentVisible now defaults to false for storage textures with *uint/*sint formats (previously true), matching the fragment shader contract that uses texture_2d<f32>. Explicitly setting fragmentVisible: true for an integer storage format now throws at material resolution with a descriptive error, replacing the generic WebGPU validation failure that surfaced during pipeline creation.
  • Renderer now honours the explicit TextureDefinition.format value when allocating source-driven (non-storage) textures. Previously the format was always re-derived from colorSpace at runtime, silently downgrading user-declared formats like rgba16float to rgba8unorm(-srgb) and triggering a one-time extra reallocation on first upload.

Fixed

  • storage: true texture definitions now fail fast when they omit explicit width/height or define a source, matching the compute-managed storage-texture runtime contract.
  • Fixed PingPongComputePass.getCurrentOutput() returning the wrong A/B buffer key after setIterations(...) was called between frames. Internal state now accumulates total iterations incrementally in advanceFrame() instead of multiplying frame count by the current iteration value, preserving correct read/write parity across iteration-count changes.
  • Fixed readStorageBuffer() leaking the staging GPUBuffer when mapAsync rejected (e.g. on device loss). The staging buffer is now destroyed on both fulfilment and rejection paths.

0.8.3 - 2026-04-19

Added

  • Added renderer and compute E2E regression coverage for asynchronous compute-shader compilation diagnostics, asserting structured compute failures surface instead of falling back to generic uncaptured-error messaging.

Fixed

  • Updated compute-pipeline compilation reporting to await async shader compilation info and validation scopes, surfacing structured COMPUTE_COMPILATION_FAILED diagnostics instead of derivative WebGPU uncaptured error / Invalid ComputePipeline cascades.

0.8.2 - 2026-04-18

Performance

  • Replaced repeated dependency-queue sort() calls and shift() in frame-registry topological scheduling with sorted insertion plus a head index, reducing scheduler rebuild overhead during task/stage graph recomputation.
  • Reused the internal resourceRefs backing array in the compute storage bind-group cache, replacing per-miss spread copies with indexed writes to reduce allocation churn when bound compute resources change.
  • Nulled out stale slots in the compute storage bind-group cache backing array after a resource-ref count shrink, topology change, or reset() call, preventing long-lived GPU object references from blocking GC in those code paths.
  • Removed the intermediate map() allocation when rebuilding activeKeys in renderer render-target sync, constructing the Set in a single pass during render-target signature changes.
  • Replaced three split('\\n') line-count scans in buildShaderSourceWithMap with allocation-free newline counting, reducing transient string-array creation during shader compilation.

Fixed

  • Refined the Svelte, React, and Vue error-overlay source snippet styling with a larger alert-message radius, rounded active-tab top corners, and a separated snippet top border treatment.

0.8.1 - 2026-04-18

Performance

  • Added packUniformsIntoFast — a validation-free uniform packing path for the renderer hot loop that skips per-entry type checks (already enforced at setUniform call time), reducing per-frame CPU overhead by ~3× compared to the public packUniformsInto path.
  • Added Float32Array.set() fast path inside writeUniformValueFast for mat4x4f uniforms backed by Float32Array, replacing a 16-element manual loop with a single native typed-array copy.
  • Returned a shared EMPTY_DIRTY_RANGES sentinel from findDirtyFloatRanges when no dirty ranges are detected, eliminating a heap allocation on every clean frame in the renderer upload path.
  • Pre-allocated canvasSurface and frameSlots objects in the renderer and mutated them in place each frame, removing per-frame { texture, view, width, height } allocations in the render path.
  • Merged two consecutive .map() iterations over uniformLayout.entries in syncMaterialRuntimeState into a single for loop, halving traversal work on material signature changes.
  • Integrated ResizeObserver into the runtime loop canvas sizing path; canvas dimensions are now read from a cached observer callback instead of calling getBoundingClientRect() (a forced layout reflow) on every animation frame.
  • Moved assertDefinedMaterial call in resolveMaterial to after the WeakMap cache check, so Object.isFrozen and field-presence guards are skipped entirely on cache hits (every steady-state per-frame call).
  • Replaced profilingHistory.shift() (O(n)) with an O(1) ring buffer in frame-registry; a head-pointer advance overwrites the oldest slot without shifting any elements, with no allocation per push.
  • Pre-allocated a closure-level clampedFrameState object in frame-registry that is mutated in place when maxDelta clamps the delta, removing the { ...state, delta } spread allocation per clamped frame.
  • Added non-function fast-path in resolveInvalidationToken — static string/symbol tokens return immediately without entering the function-resolver branch, called N-tasks × 60 fps.
  • Pre-computed frameKeyToString(key) as keyString on InternalTask at registration time, eliminating Symbol.prototype.toString() calls inside the per-frame profiling loop.

Added

  • Added packUniformsIntoFast as an internal-use export for the renderer, with JSDoc marking it @internal.
  • Added benchmark cases for packUniformsIntoFast, mat4x4f Float32Array packing, and the clean-frame dirty-ranges path to scripts/perf/core-benchmark.ts.
  • Added unit tests for mat4x4f Float32Array uniform packing (identity matrix, arbitrary values, non-zero layout offsets).
  • Added integration tests for ResizeObserver lifecycle (observe/disconnect), dimension propagation, and getBoundingClientRect fallback behavior in the runtime loop.
  • Added ring buffer correctness tests covering window saturation, shrink/grow semantics, and frameCount invariants.
  • Added frameState pre-allocation tests verifying object identity across clamped and non-clamped frames.
  • Added profiling key stability test for Symbol-keyed tasks.

Fixed

  • Improved uncaptured WebGPU error reporting to preserve and prioritize root-cause validation messages (for example dispatch-limit and binding-limit failures) instead of surfacing only derivative Invalid CommandBuffer follow-up errors.
  • Added targeted uncaptured-error classifications and hints for compute dispatch workgroup-limit violations and storage-buffer binding-size violations, with renderer + error-report tests covering the new behavior.

0.8.0 - 2026-04-11

Added

  • Added first-class Vue adapter support with dedicated @motion-core/motion-gpu/vue and @motion-core/motion-gpu/vue/advanced entrypoints.
  • Added Vue adapter runtime surface parity (FragCanvas, MotionGPUErrorOverlay, Portal, useMotionGPU, useFrame, usePointer, useTexture, and user-context helpers).
  • Added comprehensive Vue adapter test coverage, including runtime behavior, hooks, context, portal rendering, and adapter API parity.
  • Added a full Vue E2E harness with scenario parity for runtime, uniforms, textures, passes, mixed passes, lifecycle, perf, and shader recovery checks.
  • Added Vue declaration emit step (emit-vue-dts.mjs) and Vue TS config support for package type generation and validation.

Changed

  • Updated package metadata to include Vue exports (./vue, ./vue/advanced), Vue peer dependency declarations, and Vue-oriented dev tooling dependencies.
  • Updated package checks to run vue-tsc and added a dedicated e2e:serve:vue workflow for framework-scoped E2E runs.
  • Updated package build pipeline to process .vue entrypoints and include Vue plugin integration in package builds.

Fixed

  • Added Vue module shims to stabilize package-level Vue type-check workflows.
  • Stabilized Vue adapter canvas layout behavior and ensured adapter CSS is injected in Vue entry output bundles.

0.7.0 - 2026-04-07

Added

  • Added new framework-agnostic pointer helpers in core/pointer, including pointer kind normalization, coordinate conversion (px, uv, ndc), and frame-request mode resolution.
  • Added usePointer in both Svelte and React adapters with unified mouse/touch/pen support, click synthesis, lastClick state, and explicit resetClick() handling.
  • Added dedicated pointer-focused tests for core helpers and both adapter hooks (pointer.test.ts, use-pointer.test.ts, react-use-pointer.test.tsx) plus Svelte fixture coverage for outside-canvas press tracking.
  • Added extended usePointer option/callback coverage (clickButtons, clickEnabled, trackWhilePressedOutsideCanvas, callbacks, pointercancel, multi-pointer filtering) in both Svelte and React hook tests.

Changed

  • Updated playground demos (diamond, fresnel-rubiks, particle-icosahedron) to use usePointer instead of manual pointer event listener boilerplate.
  • Expanded docs and package guidance to cover pointer-hook workflows in API reference, hooks/context guides, scheduler examples, and package README/SKILL docs.
  • Normalized docs code examples by removing unnecessary escaped closing script tags in snippet templates to satisfy eslint no-useless-escape.

0.6.0 - 2026-04-06

Performance

  • Replaced Reflect.deleteProperty with the delete operator in resetRuntimeMaps and resetRenderPayloadMaps to reduce reflective API overhead when cleaning up stale uniform and texture keys after a material signature change.
  • Eliminated heap allocations in setError and syncErrorHistory by replacing spread-copy ([...errorHistory, report] / .slice()) with in-place push and splice, reducing GC pressure when error history is active.
  • Eliminated the conditional spread object and splice(0) copy in the per-frame storage-write flush path; the pending-writes array is now passed by reference and cleared in-place with length = 0 after the synchronous render() call.

Added

  • Added structured compute-stage shader diagnostics metadata (shaderStage, computeSource, compute-line source mapping) in the error diagnostics payload.
  • Added compute-source snippet support in normalized error reports for compute shader compilation failures.
  • Added dedicated compute diagnostics tests (compute-diagnostics.test.ts) including measurable classification/completeness assertions.
  • Added compute storage bind-group cache unit tests (compute-bindgroup-cache.test.ts) and renderer integration assertions for stable-frame allocation behavior.
  • Added runtime benchmark metric compute_storage_bindgroup_creations_per_1000_frames to track compute storage bind-group allocation pressure.
  • Added texture-fragment-visibility.test.ts coverage for fragmentVisible defaults and signature invalidation behavior.

Changed

  • Updated compute shader codegen with mapped variants (buildComputeShaderSourceWithMap, buildPingPongComputeShaderSourceWithMap) to preserve generated→source line metadata.
  • Updated renderer compute pipeline error handling to wrap compute pipeline creation failures as structured diagnostics with runtime context.
  • Expanded compute-focused test coverage across compute shader generation and renderer integration paths.
  • Updated renderer compute dispatch path to cache storage buffer/storage texture bind-group layouts and bind groups, invalidating only when topology or bound resources change.
  • Updated ping-pong compute binding flow to reuse prebuilt A→B / B→A bind groups instead of creating a new bind group every iteration.
  • Updated fragment-stage texture binding pipeline to respect fragmentVisible:false, excluding compute-only texture slots from fragment WGSL declarations and group(0) bind-group layouts.
  • Updated texture normalization defaults to include fragmentVisible: true and made material signatures include fragmentVisible so renderer rebuild invalidation remains deterministic.

Fixed

  • Improved compute-stage error normalization so diagnostics-backed compute failures consistently map to COMPUTE_COMPILATION_FAILED.
  • Stabilized runtime error-overlay behavior by delaying error clear until a short success window passes, preventing show/hide flicker during intermittent failures (including WEBGPU_UNCAPTURED_ERROR from compute workflows).

0.5.0 - 2026-03-30

Added

  • Added first-class compute support with new ComputePass and PingPongComputePass exports in root, core, Svelte, and React entrypoints.
  • Added storageBuffers material definitions with runtime validation (size, type, access, initialData) and immutable material snapshots.
  • Added storage-focused texture options for compute workflows (storage, format, width, height, fragmentVisible).
  • Added FrameState.writeStorageBuffer(...) and FrameState.readStorageBuffer(...) APIs for runtime CPU↔GPU storage-buffer workflows.
  • Added compute-shader contract/codegen utilities with strict @compute @workgroup_size(...) fn compute(...) validation and workgroup-size extraction.
  • Added broad compute/storage test coverage, including pass behavior, shader generation, storage runtime read/write, renderer integration, and public API snapshots.
  • Added expanded runtime error classification coverage with dedicated codes for material preprocessing, compute-contract violations, runtime resource binding failures, storage read/write bounds failures, render-graph validation failures, ping-pong configuration failures, and invalid uniform payloads.

Changed

  • Updated pass plumbing from render-only arrays to mixed AnyPass[], allowing render and compute passes to coexist in one graph.
  • Updated renderer internals to allocate/manage storage buffers and storage textures, cache compute pipelines, and flush pending storage writes during frame submission.
  • Updated material resolution/signature inputs to include storage buffer definitions and storage texture bindings, triggering deterministic rebuilds when those contracts change.
  • Updated benchmark/runtime frame-state mocks to include the new storage-buffer APIs.
  • Updated runtime-context presentation to structured multi-line formatting with pretty-printed materialSignature JSON and list-based passGraph/target sections.

Fixed

  • Added explicit compute compilation error normalization with COMPUTE_COMPILATION_FAILED classification and recovery metadata.
  • Fixed compute-only pass plans to resolve a valid final output path for canvas presentation.

0.4.2 - 2026-03-22

Changed

  • Migrated the @motion-core/motion-gpu package build pipeline from svelte-package to Vite 8 (Rolldown) while preserving multi-entrypoint ESM output (core, react, svelte, and advanced entrypoints).
  • Replaced declaration emission with a dedicated svelte2tsx step (svelte-shims-v4) and kept declaration maps enabled for published types.
  • Upgraded packages/motion-gpu from Vite 7 to Vite 8, including @sveltejs/vite-plugin-svelte compatibility updates.

Fixed

  • Restored package sourcemap emission by publishing dist/**/*.js.map generated by the build toolchain.

0.4.1 - 2026-03-22

Fixed

  • Locked the Svelte MotionGPUErrorOverlay to a dark token palette and refined overlay surfaces so source tabs/code blocks render consistently regardless of host theme.
  • Matched the React MotionGPUErrorOverlay structure and styling 1:1 with the Svelte overlay implementation.
  • Fixed missing WebGPU type globals in published declarations by patching dist/*.d.ts with @webgpu/types references and keeping d.ts.map line mappings aligned after the header injection.

0.4.0 - 2026-03-22

Added

  • Added full React adapter support with dedicated react and react/advanced package entrypoints.
  • Added React FragCanvas runtime integration, including error overlay and portal support.
  • Added React runtime context/frame hooks and typed user-context helpers.
  • Added React useTexture hook parity with runtime texture workflows.
  • Added React adapter test coverage across runtime, hooks, context, portal, and public API integration.
  • Added TSX support to the docs Shiki highlighter.

Changed

  • Updated package metadata and peer dependencies to include React/React DOM support.
  • Expanded README and docs to cover React adapter setup, usage, and advanced APIs.
  • Updated docs hero copy and replaced the hero preview image asset.

Fixed

  • Added support for lazy options inputs in Svelte useTexture.
  • Adopted Svelte attachments patterns in adapter components for parity and consistency.

0.3.0 - 2026-03-21

Added

  • Added structured runtime error metadata: stable code, severity, and recoverability fields in normalized error reports.
  • Added runtime context attachment to shader diagnostics for better compile/runtime triage.
  • Added an optional runtime error history buffer in the FragCanvas runtime flow.
  • Normalized useTexture hook failures into MotionGPUErrorReport payloads.

Changed

  • Added explicit .js specifiers in published ESM paths for better cross-runtime compatibility.
  • Extracted a shared fullscreen pass pipeline lifecycle used by fullscreen pass implementations.
  • Added Context7 links in root/package documentation for AI documentation access.
  • Changed default error dialog font weight in MotionGPUErrorOverlay from 300 to 400.

Fixed

  • Guarded the runtime loop against exceptions thrown inside user onError handlers.
  • Deduplicated repeated runtime error reports to reduce duplicate reporting noise.
  • Deduplicated CurrentWritable#set() updates to skip redundant reactive notifications.
  • Fixed error overlay source label mapping to consistently use mapped source labels.

Performance

  • Improved uniform upload batching by merging nearby dirty ranges before writeBuffer calls.
  • Added a configurable threshold for dirty-range merge behavior.

Documentation

  • Aligned error-reporting docs with the latest runtime API.

0.2.0 - 2026-03-14

Added

  • Added explicit multi-layer entrypoints: root (@motion-core/motion-gpu), advanced, svelte, svelte/advanced, core, and core/advanced.
  • Split and standardized API documentation by domain (core, hooks, material, passes, advanced).
  • Added named render-target pass graph support for multi-pass pipelines.
  • Added advanced scheduler helpers and expanded scheduler diagnostics workflows.
  • Added source-mapped shader diagnostics overlay and improved fragment-contract diagnostics.
  • Added benchmark baselines and expanded unit/e2e test coverage for runtime paths.

Changed

  • Refactored architecture to separate framework-agnostic core from the Svelte adapter layer.
  • Split user context API into dedicated read/write operations.
  • Prepared package metadata and publish workflow for public npm distribution.

Fixed

  • Stabilized FragCanvas sizing and frame payload synchronization.
  • Hardened scheduler dependency validation and init-error recovery behavior.
  • Improved texture lifecycle management (blob eviction, allocation reuse, metadata preservation, reload reliability).
  • Reduced idle RAF work in manual and on-demand modes and improved wakeups on context changes.

0.1.0 - 2026-02-27

Added

  • Initial MotionGPU release with FragCanvas as the primary Svelte runtime entrypoint.
  • Material pipeline with immutable defineMaterial contracts and runtime material hot-swap support.
  • Typed uniform system with runtime layout validation and dirty-range uploads.
  • Texture pipeline with WGSL bindings, sampler configuration, mipmap/anisotropy/video support, and useTexture.
  • Frame scheduler with staged useFrame tasks, invalidation control, diagnostics, and profiling hooks.
  • Render graph with fullscreen pass primitives and named render targets.
  • Error handling pipeline for WebGPU device-loss/uncaptured errors with fullscreen overlay support.
  • Shader preprocessing via includes/defines and compile diagnostics mapping.
  • Namespaced user-context APIs for plugin-like integrations.
  • Core tests and TypeScript hardening across runtime/public API behavior.