@motion-core/motion-gpu 0.2.0 → 0.3.0

package/README.md

@@ -157,6 +157,12 @@ npm i @motion-core/motion-gpu
 
 ---
 
+# AI Documentation
+
+MotionGPU documentation is also available for AI tools via [Context7](https://context7.com/motion-core/motion-gpu).
+
+---
+
 # Quick Start
 
 ## 1. Create a material and render it

package/dist/core/current-value.js

@@ -10,6 +10,9 @@ export function createCurrentWritable(initialValue, onChange) {
         }
     };
     const set = (value) => {
+        if (Object.is(current, value)) {
+            return;
+        }
         current = value;
         notify(value);
         onChange?.(value);

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

@@ -19,6 +19,19 @@ export interface ShaderCompilationDiagnostic {
     lineLength?: number;
     sourceLocation: MaterialSourceLocation | null;
 }
+/**
+ * Runtime context snapshot captured for shader compilation diagnostics.
+ */
+export interface ShaderCompilationRuntimeContext {
+    materialSignature?: string;
+    passGraph?: {
+        passCount: number;
+        enabledPassCount: number;
+        inputs: string[];
+        outputs: string[];
+    };
+    activeRenderTargets: string[];
+}
 /**
  * Structured payload attached to WGSL compilation errors.
  */
@@ -29,6 +42,7 @@ export interface ShaderCompilationDiagnosticsPayload {
     includeSources: Record<string, string>;
     defineBlockSource?: string;
     materialSource: MaterialSourceMetadata | null;
+    runtimeContext?: ShaderCompilationRuntimeContext;
 }
 /**
  * Attaches structured diagnostics payload to an Error.

package/dist/core/error-diagnostics.js

@@ -56,6 +56,39 @@ function isShaderCompilationDiagnostic(value) {
     }
     return true;
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+function isShaderCompilationRuntimeContext(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    if (record.materialSignature !== undefined && typeof record.materialSignature !== 'string') {
+        return false;
+    }
+    if (!isStringArray(record.activeRenderTargets)) {
+        return false;
+    }
+    const passGraph = record.passGraph;
+    if (passGraph === undefined) {
+        return true;
+    }
+    if (passGraph === null || typeof passGraph !== 'object') {
+        return false;
+    }
+    const passGraphRecord = passGraph;
+    if (typeof passGraphRecord.passCount !== 'number') {
+        return false;
+    }
+    if (typeof passGraphRecord.enabledPassCount !== 'number') {
+        return false;
+    }
+    if (!isStringArray(passGraphRecord.inputs) || !isStringArray(passGraphRecord.outputs)) {
+        return false;
+    }
+    return true;
+}
 /**
  * Attaches structured diagnostics payload to an Error.
  */
@@ -98,6 +131,10 @@ export function getShaderCompilationDiagnostics(error) {
     if (record.materialSource !== null && !isMaterialSourceMetadata(record.materialSource)) {
         return null;
     }
+    if (record.runtimeContext !== undefined &&
+        !isShaderCompilationRuntimeContext(record.runtimeContext)) {
+        return null;
+    }
     return {
         kind: 'shader-compilation',
         diagnostics: record.diagnostics,
@@ -106,6 +143,9 @@ export function getShaderCompilationDiagnostics(error) {
         ...(record.defineBlockSource !== undefined
             ? { defineBlockSource: record.defineBlockSource }
             : {}),
-        materialSource: (record.materialSource ?? null)
+        materialSource: (record.materialSource ?? null),
+        ...(record.runtimeContext !== undefined
+            ? { runtimeContext: record.runtimeContext }
+            : {})
     };
 }

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

@@ -2,6 +2,14 @@
  * Runtime phase in which an error occurred.
  */
 export type MotionGPUErrorPhase = 'initialization' | 'render';
+/**
+ * Stable machine-readable error category code.
+ */
+export type MotionGPUErrorCode = 'WEBGPU_UNAVAILABLE' | 'WEBGPU_ADAPTER_UNAVAILABLE' | 'WEBGPU_CONTEXT_UNAVAILABLE' | 'WGSL_COMPILATION_FAILED' | 'WEBGPU_DEVICE_LOST' | 'WEBGPU_UNCAPTURED_ERROR' | 'BIND_GROUP_MISMATCH' | 'TEXTURE_USAGE_INVALID' | 'TEXTURE_REQUEST_FAILED' | 'TEXTURE_DECODE_UNAVAILABLE' | 'TEXTURE_REQUEST_ABORTED' | 'MOTIONGPU_RUNTIME_ERROR';
+/**
+ * Severity level for user-facing diagnostics.
+ */
+export type MotionGPUErrorSeverity = 'error' | 'fatal';
 /**
  * One source-code line displayed in diagnostics snippet.
  */
@@ -20,10 +28,35 @@ export interface MotionGPUErrorSource {
     column?: number;
     snippet: MotionGPUErrorSourceLine[];
 }
+/**
+ * Optional runtime context captured with diagnostics payload.
+ */
+export interface MotionGPUErrorContext {
+    materialSignature?: string;
+    passGraph?: {
+        passCount: number;
+        enabledPassCount: number;
+        inputs: string[];
+        outputs: string[];
+    };
+    activeRenderTargets: string[];
+}
 /**
  * Structured error payload used by UI diagnostics.
  */
 export interface MotionGPUErrorReport {
+    /**
+     * Stable machine-readable category code.
+     */
+    code: MotionGPUErrorCode;
+    /**
+     * Severity level used by diagnostics UIs and telemetry.
+     */
+    severity: MotionGPUErrorSeverity;
+    /**
+     * Whether runtime may recover without full renderer re-creation.
+     */
+    recoverable: boolean;
     /**
      * Short category title.
      */
@@ -56,6 +89,10 @@ export interface MotionGPUErrorReport {
      * Optional source context for shader-related diagnostics.
      */
     source: MotionGPUErrorSource | null;
+    /**
+     * Optional runtime context snapshot (material/pass graph/render targets).
+     */
+    context: MotionGPUErrorContext | null;
 }
 /**
  * Converts unknown errors to a consistent, display-ready error report.

package/dist/core/error-report.js

@@ -98,53 +98,107 @@ function formatDiagnosticMessage(entry) {
 function classifyErrorMessage(message) {
     if (message.includes('WebGPU is not available in this browser')) {
         return {
+            code: 'WEBGPU_UNAVAILABLE',
+            severity: 'fatal',
+            recoverable: false,
             title: 'WebGPU unavailable',
             hint: 'Use a browser with WebGPU enabled (latest Chrome/Edge/Safari TP) and secure context.'
         };
     }
     if (message.includes('Unable to acquire WebGPU adapter')) {
         return {
+            code: 'WEBGPU_ADAPTER_UNAVAILABLE',
+            severity: 'fatal',
+            recoverable: false,
             title: 'WebGPU adapter unavailable',
             hint: 'GPU adapter request failed. Check browser permissions, flags and device support.'
         };
     }
     if (message.includes('Canvas does not support webgpu context')) {
         return {
+            code: 'WEBGPU_CONTEXT_UNAVAILABLE',
+            severity: 'error',
+            recoverable: true,
             title: 'Canvas cannot create WebGPU context',
             hint: 'Make sure this canvas is attached to DOM and not using an unsupported context option.'
         };
     }
     if (message.includes('WGSL compilation failed')) {
         return {
+            code: 'WGSL_COMPILATION_FAILED',
+            severity: 'error',
+            recoverable: true,
             title: 'WGSL compilation failed',
             hint: 'Check WGSL line numbers below and verify struct/binding/function signatures.'
         };
     }
     if (message.includes('WebGPU device lost') || message.includes('Device Lost')) {
         return {
+            code: 'WEBGPU_DEVICE_LOST',
+            severity: 'fatal',
+            recoverable: false,
             title: 'WebGPU device lost',
             hint: 'GPU device/context was lost. Recreate the renderer and check OS/GPU stability.'
         };
     }
     if (message.includes('WebGPU uncaptured error')) {
         return {
+            code: 'WEBGPU_UNCAPTURED_ERROR',
+            severity: 'error',
+            recoverable: true,
             title: 'WebGPU uncaptured error',
             hint: 'A GPU command failed asynchronously. Review details and validate resource/state usage.'
         };
     }
     if (message.includes('CreateBindGroup') || message.includes('bind group layout')) {
         return {
+            code: 'BIND_GROUP_MISMATCH',
+            severity: 'error',
+            recoverable: true,
             title: 'Bind group mismatch',
             hint: 'Bindings in shader and runtime resources are out of sync. Verify uniforms/textures layout.'
         };
     }
     if (message.includes('Destination texture needs to have CopyDst')) {
         return {
+            code: 'TEXTURE_USAGE_INVALID',
+            severity: 'error',
+            recoverable: true,
             title: 'Invalid texture usage flags',
             hint: 'Texture used as upload destination must include CopyDst (and often RenderAttachment).'
         };
     }
+    if (message.includes('Texture request failed')) {
+        return {
+            code: 'TEXTURE_REQUEST_FAILED',
+            severity: 'error',
+            recoverable: true,
+            title: 'Texture request failed',
+            hint: 'Verify texture URL, CORS policy and response status before retrying.'
+        };
+    }
+    if (message.includes('createImageBitmap is not available in this runtime')) {
+        return {
+            code: 'TEXTURE_DECODE_UNAVAILABLE',
+            severity: 'fatal',
+            recoverable: false,
+            title: 'Texture decode unavailable',
+            hint: 'Runtime lacks createImageBitmap support. Use a browser/runtime with image bitmap decoding.'
+        };
+    }
+    if (message.toLowerCase().includes('texture request was aborted')) {
+        return {
+            code: 'TEXTURE_REQUEST_ABORTED',
+            severity: 'error',
+            recoverable: true,
+            title: 'Texture request aborted',
+            hint: 'Texture load was cancelled. Retry the request when source inputs stabilize.'
+        };
+    }
     return {
+        code: 'MOTIONGPU_RUNTIME_ERROR',
+        severity: 'error',
+        recoverable: true,
         title: 'MotionGPU render error',
         hint: 'Review technical details below. If issue persists, isolate shader/uniform/texture changes.'
     };
@@ -167,6 +221,7 @@ export function toMotionGPUErrorReport(error, phase) {
     const defaultMessage = rawLines[0] ?? rawMessage;
     const defaultDetails = rawLines.slice(1);
     const source = buildSourceFromDiagnostics(error);
+    const context = shaderDiagnostics?.runtimeContext ?? null;
     const message = shaderDiagnostics && shaderDiagnostics.diagnostics[0]
         ? formatDiagnosticMessage(shaderDiagnostics.diagnostics[0])
         : defaultMessage;
@@ -178,6 +233,9 @@ export function toMotionGPUErrorReport(error, phase) {
         : [];
     const classification = classifyErrorMessage(rawMessage);
     return {
+        code: classification.code,
+        severity: classification.severity,
+        recoverable: classification.recoverable,
         title: classification.title,
         message,
         hint: classification.hint,
@@ -185,6 +243,7 @@ export function toMotionGPUErrorReport(error, phase) {
         stack,
         rawMessage,
         phase,
-        source
+        source,
+        context
     };
 }

package/dist/core/index.d.ts

@@ -11,7 +11,7 @@ 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 { MotionGPUErrorCode, MotionGPUErrorContext, MotionGPUErrorPhase, MotionGPUErrorReport, MotionGPUErrorSeverity, 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';

package/dist/core/renderer.d.ts

@@ -1,4 +1,14 @@
 import type { Renderer, RendererOptions } from './types.js';
+/**
+ * Computes dirty float ranges between two uniform snapshots.
+ *
+ * Adjacent dirty ranges separated by a gap smaller than or equal to
+ * {@link DIRTY_RANGE_MERGE_GAP} are merged to reduce `writeBuffer` calls.
+ */
+export declare function findDirtyFloatRanges(previous: Float32Array, next: Float32Array, mergeGapThreshold?: number): Array<{
+    start: number;
+    count: number;
+}>;
 /**
  * Creates the WebGPU renderer used by `FragCanvas`.
  *

package/dist/core/renderer.js

@@ -78,9 +78,45 @@ async function assertCompilation(module, options) {
         ...(options?.defineBlockSource !== undefined
             ? { defineBlockSource: options.defineBlockSource }
             : {}),
-        materialSource: options?.materialSource ?? null
+        materialSource: options?.materialSource ?? null,
+        ...(options?.runtimeContext !== undefined ? { runtimeContext: options.runtimeContext } : {})
     });
 }
+function toSortedUniqueStrings(values) {
+    return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
+}
+function buildPassGraphSnapshot(passes) {
+    const declaredPasses = passes ?? [];
+    let enabledPassCount = 0;
+    const inputs = [];
+    const outputs = [];
+    for (const pass of declaredPasses) {
+        if (pass.enabled === false) {
+            continue;
+        }
+        enabledPassCount += 1;
+        const needsSwap = pass.needsSwap ?? true;
+        const input = pass.input ?? 'source';
+        const output = pass.output ?? (needsSwap ? 'target' : 'source');
+        inputs.push(input);
+        outputs.push(output);
+    }
+    return {
+        passCount: declaredPasses.length,
+        enabledPassCount,
+        inputs: toSortedUniqueStrings(inputs),
+        outputs: toSortedUniqueStrings(outputs)
+    };
+}
+function buildShaderCompilationRuntimeContext(options) {
+    const passList = options.getPasses?.() ?? options.passes;
+    const renderTargetMap = options.getRenderTargets?.() ?? options.renderTargets;
+    return {
+        ...(options.materialSignature ? { materialSignature: options.materialSignature } : {}),
+        passGraph: buildPassGraphSnapshot(passList),
+        activeRenderTargets: Object.keys(renderTargetMap ?? {}).sort((a, b) => a.localeCompare(b))
+    };
+}
 /**
  * Creates a 1x1 white fallback texture used before user textures become available.
  */
@@ -182,10 +218,19 @@ function createBindGroupLayoutEntries(textureBindings) {
     }
     return entries;
 }
+/**
+ * Maximum gap (in floats) between two dirty ranges that triggers merge.
+ *
+ * Set to 4 (16 bytes) which covers one vec4f alignment slot.
+ */
+const DIRTY_RANGE_MERGE_GAP = 4;
 /**
  * Computes dirty float ranges between two uniform snapshots.
+ *
+ * Adjacent dirty ranges separated by a gap smaller than or equal to
+ * {@link DIRTY_RANGE_MERGE_GAP} are merged to reduce `writeBuffer` calls.
  */
-function findDirtyFloatRanges(previous, next) {
+export function findDirtyFloatRanges(previous, next, mergeGapThreshold = DIRTY_RANGE_MERGE_GAP) {
     const ranges = [];
     let start = -1;
     for (let index = 0; index < next.length; index += 1) {
@@ -203,7 +248,22 @@ function findDirtyFloatRanges(previous, next) {
     if (start !== -1) {
         ranges.push({ start, count: next.length - start });
     }
-    return ranges;
+    if (ranges.length <= 1) {
+        return ranges;
+    }
+    const merged = [ranges[0]];
+    for (let index = 1; index < ranges.length; index += 1) {
+        const prev = merged[merged.length - 1];
+        const curr = ranges[index];
+        const gap = curr.start - (prev.start + prev.count);
+        if (gap <= mergeGapThreshold) {
+            prev.count = curr.start + curr.count - prev.start;
+        }
+        else {
+            merged.push(curr);
+        }
+    }
+    return merged;
 }
 /**
  * Determines whether shader output should perform linear-to-sRGB conversion.
@@ -339,6 +399,7 @@ export async function createRenderer(options) {
     };
     device.addEventListener('uncapturederror', handleUncapturedError);
     try {
+        const runtimeContext = buildShaderCompilationRuntimeContext(options);
         const convertLinearToSrgb = shouldConvertLinearToSrgb(options.outputColorSpace, format);
         const builtShader = buildShaderSourceWithMap(options.fragmentWgsl, options.uniformLayout, options.textureKeys, {
             convertLinearToSrgb,
@@ -352,7 +413,8 @@ export async function createRenderer(options) {
             ...(options.defineBlockSource !== undefined
                 ? { defineBlockSource: options.defineBlockSource }
                 : {}),
-            materialSource: options.materialSource ?? null
+            materialSource: options.materialSource ?? null,
+            runtimeContext
         });
         const normalizedTextureDefinitions = normalizeTextureDefinitions(options.textureDefinitions, options.textureKeys);
         const textureBindings = options.textureKeys.map((key, index) => {

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

@@ -21,6 +21,9 @@ export interface MotionGPURuntimeLoopOptions {
     getDeviceDescriptor: () => GPUDeviceDescriptor | undefined;
     getOnError: () => ((report: MotionGPUErrorReport) => void) | undefined;
     reportError: (report: MotionGPUErrorReport | null) => void;
+    getErrorHistoryLimit?: () => number | undefined;
+    getOnErrorHistory?: () => ((history: MotionGPUErrorReport[]) => void) | undefined;
+    reportErrorHistory?: (history: MotionGPUErrorReport[]) => void;
 }
 export interface MotionGPURuntimeLoop {
     requestFrame: () => void;

package/dist/core/runtime-loop.js

@@ -33,12 +33,81 @@ export function createMotionGPURuntimeLoop(options) {
     const renderTextures = {};
     const canvasSize = { width: 0, height: 0 };
     let shouldContinueAfterFrame = false;
+    let activeErrorKey = null;
+    let errorHistory = [];
+    const getHistoryLimit = () => {
+        const value = options.getErrorHistoryLimit?.() ?? 0;
+        if (!Number.isFinite(value) || value <= 0) {
+            return 0;
+        }
+        return Math.floor(value);
+    };
+    const publishErrorHistory = () => {
+        options.reportErrorHistory?.(errorHistory);
+        const onErrorHistory = options.getOnErrorHistory?.();
+        if (!onErrorHistory) {
+            return;
+        }
+        try {
+            onErrorHistory(errorHistory);
+        }
+        catch {
+            // User-provided error history handlers must not break runtime error recovery.
+        }
+    };
+    const syncErrorHistory = () => {
+        const limit = getHistoryLimit();
+        if (limit <= 0) {
+            if (errorHistory.length === 0) {
+                return;
+            }
+            errorHistory = [];
+            publishErrorHistory();
+            return;
+        }
+        if (errorHistory.length <= limit) {
+            return;
+        }
+        errorHistory = errorHistory.slice(errorHistory.length - limit);
+        publishErrorHistory();
+    };
     const setError = (error, phase) => {
         const report = toMotionGPUErrorReport(error, phase);
+        const reportKey = JSON.stringify({
+            phase: report.phase,
+            title: report.title,
+            message: report.message,
+            rawMessage: report.rawMessage
+        });
+        if (activeErrorKey === reportKey) {
+            return;
+        }
+        activeErrorKey = reportKey;
+        const historyLimit = getHistoryLimit();
+        if (historyLimit > 0) {
+            errorHistory = [...errorHistory, report];
+            if (errorHistory.length > historyLimit) {
+                errorHistory = errorHistory.slice(errorHistory.length - historyLimit);
+            }
+            publishErrorHistory();
+        }
         options.reportError(report);
-        options.getOnError()?.(report);
+        const onError = options.getOnError();
+        if (!onError) {
+            return;
+        }
+        try {
+            onError(report);
+        }
+        catch {
+            // User-provided error handlers must not break runtime error recovery.
+        }
     };
     const clearError = () => {
+        if (activeErrorKey === null) {
+            return;
+        }
+        activeErrorKey = null;
         options.reportError(null);
     };
     const scheduleFrame = () => {
@@ -127,6 +196,7 @@ export function createMotionGPURuntimeLoop(options) {
         if (isDisposed) {
             return;
         }
+        syncErrorHistory();
         let materialState;
         try {
             materialState = resolveActiveMaterial();
@@ -165,6 +235,7 @@ export function createMotionGPURuntimeLoop(options) {
                             includeSources: materialState.includeSources,
                             defineBlockSource: materialState.defineBlockSource,
                             materialSource: materialState.source,
+                            materialSignature: materialState.signature,
                             uniformLayout: materialState.uniformLayout,
                             textureKeys: materialState.textureKeys,
                             textureDefinitions: materialState.textures,

package/dist/core/types.d.ts

@@ -443,6 +443,10 @@ export interface RendererOptions {
         column?: number;
         functionName?: string;
     } | null;
+    /**
+     * Stable material signature captured during resolution.
+     */
+    materialSignature?: string;
     /**
      * Resolved uniform layout.
      */

package/dist/passes/BlitPass.d.ts

@@ -1,32 +1,11 @@
-import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types.js';
-export interface BlitPassOptions extends RenderPassFlags {
-    enabled?: boolean;
-    needsSwap?: boolean;
-    input?: RenderPassInputSlot;
-    output?: RenderPassOutputSlot;
-    filter?: GPUFilterMode;
-}
+import { FullscreenPass, type FullscreenPassOptions } from './FullscreenPass.js';
+export type BlitPassOptions = FullscreenPassOptions;
 /**
  * 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;
+export declare class BlitPass extends FullscreenPass {
+    protected getProgram(): string;
     constructor(options?: BlitPassOptions);
-    private ensureResources;
-    setSize(width: number, height: number): void;
-    render(context: RenderPassContext): void;
-    dispose(): void;
+    protected getVertexEntryPoint(): string;
+    protected getFragmentEntryPoint(): string;
 }