@motion-core/motion-gpu 0.1.0

package/dist/core/error-diagnostics.js

@@ -0,0 +1,111 @@
+function isMaterialSourceMetadata(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    if (record.component !== undefined && typeof record.component !== 'string') {
+        return false;
+    }
+    if (record.file !== undefined && typeof record.file !== 'string') {
+        return false;
+    }
+    if (record.functionName !== undefined && typeof record.functionName !== 'string') {
+        return false;
+    }
+    if (record.line !== undefined && typeof record.line !== 'number') {
+        return false;
+    }
+    if (record.column !== undefined && typeof record.column !== 'number') {
+        return false;
+    }
+    return true;
+}
+function isMaterialSourceLocation(value) {
+    if (value === null) {
+        return true;
+    }
+    if (typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    const kind = record.kind;
+    if (kind !== 'fragment' && kind !== 'include' && kind !== 'define') {
+        return false;
+    }
+    return typeof record.line === 'number';
+}
+function isShaderCompilationDiagnostic(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    if (typeof record.generatedLine !== 'number') {
+        return false;
+    }
+    if (typeof record.message !== 'string') {
+        return false;
+    }
+    if (record.linePos !== undefined && typeof record.linePos !== 'number') {
+        return false;
+    }
+    if (record.lineLength !== undefined && typeof record.lineLength !== 'number') {
+        return false;
+    }
+    if (!isMaterialSourceLocation(record.sourceLocation)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Attaches structured diagnostics payload to an Error.
+ */
+export function attachShaderCompilationDiagnostics(error, payload) {
+    error.motiongpuDiagnostics = payload;
+    return error;
+}
+/**
+ * Extracts structured diagnostics payload from unknown error value.
+ */
+export function getShaderCompilationDiagnostics(error) {
+    if (!(error instanceof Error)) {
+        return null;
+    }
+    const payload = error.motiongpuDiagnostics;
+    if (payload === null || typeof payload !== 'object') {
+        return null;
+    }
+    const record = payload;
+    if (record.kind !== 'shader-compilation') {
+        return null;
+    }
+    if (!Array.isArray(record.diagnostics) ||
+        !record.diagnostics.every(isShaderCompilationDiagnostic)) {
+        return null;
+    }
+    if (typeof record.fragmentSource !== 'string') {
+        return null;
+    }
+    if (record.defineBlockSource !== undefined && typeof record.defineBlockSource !== 'string') {
+        return null;
+    }
+    if (record.includeSources === null || typeof record.includeSources !== 'object') {
+        return null;
+    }
+    const includeSources = record.includeSources;
+    if (Object.values(includeSources).some((value) => typeof value !== 'string')) {
+        return null;
+    }
+    if (record.materialSource !== null && !isMaterialSourceMetadata(record.materialSource)) {
+        return null;
+    }
+    return {
+        kind: 'shader-compilation',
+        diagnostics: record.diagnostics,
+        fragmentSource: record.fragmentSource,
+        includeSources: includeSources,
+        ...(record.defineBlockSource !== undefined
+            ? { defineBlockSource: record.defineBlockSource }
+            : {}),
+        materialSource: (record.materialSource ?? null)
+    };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Runtime phase in which an error occurred.
+ */
+export type MotionGPUErrorPhase = 'initialization' | 'render';
+/**
+ * One source-code line displayed in diagnostics snippet.
+ */
+export interface MotionGPUErrorSourceLine {
+    number: number;
+    code: string;
+    highlight: boolean;
+}
+/**
+ * Structured source context displayed for shader compilation errors.
+ */
+export interface MotionGPUErrorSource {
+    component: string;
+    location: string;
+    line: number;
+    column?: number;
+    snippet: MotionGPUErrorSourceLine[];
+}
+/**
+ * Structured error payload used by UI diagnostics.
+ */
+export interface MotionGPUErrorReport {
+    /**
+     * Short category title.
+     */
+    title: string;
+    /**
+     * Primary human-readable message.
+     */
+    message: string;
+    /**
+     * Suggested remediation hint.
+     */
+    hint: string;
+    /**
+     * Additional parsed details (for example WGSL line errors).
+     */
+    details: string[];
+    /**
+     * Stack trace lines when available.
+     */
+    stack: string[];
+    /**
+     * Original unmodified message.
+     */
+    rawMessage: string;
+    /**
+     * Runtime phase where the error occurred.
+     */
+    phase: MotionGPUErrorPhase;
+    /**
+     * Optional source context for shader-related diagnostics.
+     */
+    source: MotionGPUErrorSource | null;
+}
+/**
+ * Converts unknown errors to a consistent, display-ready error report.
+ *
+ * @param error - Unknown thrown value.
+ * @param phase - Phase during which error occurred.
+ * @returns Normalized error report.
+ */
+export declare function toMotionGPUErrorReport(error: unknown, phase: MotionGPUErrorPhase): MotionGPUErrorReport;

package/dist/core/error-report.js

@@ -0,0 +1,190 @@
+import { getShaderCompilationDiagnostics } from './error-diagnostics';
+import { formatShaderSourceLocation } from './shader';
+/**
+ * Splits multi-line values into trimmed non-empty lines.
+ */
+function splitLines(value) {
+    return value
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function toDisplayName(path) {
+    const normalized = path.split(/[?#]/)[0] ?? path;
+    const chunks = normalized.split(/[\\/]/);
+    const last = chunks[chunks.length - 1];
+    return last && last.length > 0 ? last : path;
+}
+function toSnippet(source, line, radius = 3) {
+    const lines = source.replace(/\r\n?/g, '\n').split('\n');
+    if (lines.length === 0) {
+        return [];
+    }
+    const targetLine = Math.min(Math.max(1, line), lines.length);
+    const start = Math.max(1, targetLine - radius);
+    const end = Math.min(lines.length, targetLine + radius);
+    const snippet = [];
+    for (let index = start; index <= end; index += 1) {
+        snippet.push({
+            number: index,
+            code: lines[index - 1] ?? '',
+            highlight: index === targetLine
+        });
+    }
+    return snippet;
+}
+function buildSourceFromDiagnostics(error) {
+    const diagnostics = getShaderCompilationDiagnostics(error);
+    if (!diagnostics || diagnostics.diagnostics.length === 0) {
+        return null;
+    }
+    const primary = diagnostics.diagnostics.find((entry) => entry.sourceLocation !== null);
+    if (!primary?.sourceLocation) {
+        return null;
+    }
+    const location = primary.sourceLocation;
+    const column = primary.linePos && primary.linePos > 0 ? primary.linePos : undefined;
+    if (location.kind === 'fragment') {
+        const component = diagnostics.materialSource?.component ??
+            (diagnostics.materialSource?.file
+                ? toDisplayName(diagnostics.materialSource.file)
+                : 'User shader fragment');
+        const locationLabel = formatShaderSourceLocation(location) ?? `fragment line ${location.line}`;
+        return {
+            component,
+            location: `${component} (${locationLabel})`,
+            line: location.line,
+            ...(column !== undefined ? { column } : {}),
+            snippet: toSnippet(diagnostics.fragmentSource, location.line)
+        };
+    }
+    if (location.kind === 'include') {
+        const includeName = location.include ?? 'unknown';
+        const includeSource = diagnostics.includeSources[includeName] ?? '';
+        const component = `#include <${includeName}>`;
+        const locationLabel = formatShaderSourceLocation(location) ?? `include <${includeName}>`;
+        return {
+            component,
+            location: `${component} (${locationLabel})`,
+            line: location.line,
+            ...(column !== undefined ? { column } : {}),
+            snippet: toSnippet(includeSource, location.line)
+        };
+    }
+    const defineName = location.define ?? 'unknown';
+    const defineLine = Math.max(1, location.line);
+    const component = `#define ${defineName}`;
+    const locationLabel = formatShaderSourceLocation(location) ?? `define "${defineName}" line ${defineLine}`;
+    return {
+        component,
+        location: `${component} (${locationLabel})`,
+        line: defineLine,
+        ...(column !== undefined ? { column } : {}),
+        snippet: toSnippet(diagnostics.defineBlockSource ?? '', defineLine, 2)
+    };
+}
+function formatDiagnosticMessage(entry) {
+    const sourceLabel = formatShaderSourceLocation(entry.sourceLocation);
+    const generatedLineLabel = entry.generatedLine > 0 ? `generated WGSL line ${entry.generatedLine}` : null;
+    const labels = [sourceLabel, generatedLineLabel].filter((value) => Boolean(value));
+    if (labels.length === 0) {
+        return entry.message;
+    }
+    return `[${labels.join(' | ')}] ${entry.message}`;
+}
+/**
+ * Maps known WebGPU/WGSL error patterns to a user-facing title and hint.
+ */
+function classifyErrorMessage(message) {
+    if (message.includes('WebGPU is not available in this browser')) {
+        return {
+            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 {
+            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 {
+            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 {
+            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 {
+            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 {
+            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 {
+            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 {
+            title: 'Invalid texture usage flags',
+            hint: 'Texture used as upload destination must include CopyDst (and often RenderAttachment).'
+        };
+    }
+    return {
+        title: 'MotionGPU render error',
+        hint: 'Review technical details below. If issue persists, isolate shader/uniform/texture changes.'
+    };
+}
+/**
+ * Converts unknown errors to a consistent, display-ready error report.
+ *
+ * @param error - Unknown thrown value.
+ * @param phase - Phase during which error occurred.
+ * @returns Normalized error report.
+ */
+export function toMotionGPUErrorReport(error, phase) {
+    const shaderDiagnostics = getShaderCompilationDiagnostics(error);
+    const rawMessage = error instanceof Error
+        ? error.message
+        : typeof error === 'string'
+            ? error
+            : 'Unknown FragCanvas error';
+    const rawLines = splitLines(rawMessage);
+    const defaultMessage = rawLines[0] ?? rawMessage;
+    const defaultDetails = rawLines.slice(1);
+    const source = buildSourceFromDiagnostics(error);
+    const message = shaderDiagnostics && shaderDiagnostics.diagnostics[0]
+        ? formatDiagnosticMessage(shaderDiagnostics.diagnostics[0])
+        : defaultMessage;
+    const details = shaderDiagnostics
+        ? shaderDiagnostics.diagnostics.slice(1).map((entry) => formatDiagnosticMessage(entry))
+        : defaultDetails;
+    const stack = error instanceof Error && error.stack
+        ? splitLines(error.stack).filter((line) => line !== message)
+        : [];
+    const classification = classifyErrorMessage(rawMessage);
+    return {
+        title: classification.title,
+        message,
+        hint: classification.hint,
+        details,
+        stack,
+        rawMessage,
+        phase,
+        source
+    };
+}

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

@@ -0,0 +1,63 @@
+import type { MaterialDefineValue, MaterialDefines, MaterialIncludes } from './material';
+/**
+ * Source location metadata for one generated fragment line.
+ */
+export interface MaterialSourceLocation {
+    /**
+     * Origin category for this generated line.
+     */
+    kind: 'fragment' | 'include' | 'define';
+    /**
+     * 1-based line in the origin source.
+     */
+    line: number;
+    /**
+     * Include chunk identifier when `kind === "include"`.
+     */
+    include?: string;
+    /**
+     * Define identifier when `kind === "define"`.
+     */
+    define?: string;
+}
+/**
+ * 1-based line map from generated fragment WGSL to user source locations.
+ */
+export type MaterialLineMap = Array<MaterialSourceLocation | null>;
+/**
+ * Preprocess output used by material resolution and diagnostics mapping.
+ */
+export interface PreprocessedMaterialFragment {
+    /**
+     * Final fragment source after defines/include expansion.
+     */
+    fragment: string;
+    /**
+     * 1-based generated-line source map.
+     */
+    lineMap: MaterialLineMap;
+    /**
+     * Deterministic WGSL define block used to build the final fragment source.
+     */
+    defineBlockSource: string;
+}
+/**
+ * Validates and normalizes define entries.
+ */
+export declare function normalizeDefines(defines: MaterialDefines | undefined): MaterialDefines;
+/**
+ * Validates include map identifiers and source chunks.
+ */
+export declare function normalizeIncludes(includes: MaterialIncludes | undefined): MaterialIncludes;
+/**
+ * Converts one define declaration to WGSL `const`.
+ */
+export declare function toDefineLine(key: string, value: MaterialDefineValue): string;
+/**
+ * Preprocesses material fragment with deterministic define/include expansion and line mapping.
+ */
+export declare function preprocessMaterialFragment(input: {
+    fragment: string;
+    defines?: MaterialDefines;
+    includes?: MaterialIncludes;
+}): PreprocessedMaterialFragment;

package/dist/core/material-preprocess.js

@@ -0,0 +1,166 @@
+import { assertUniformName } from './uniforms';
+const INCLUDE_DIRECTIVE_PATTERN = /^\s*#include\s+<([A-Za-z_][A-Za-z0-9_]*)>\s*$/;
+function normalizeTypedDefine(name, define) {
+    const value = define.value;
+    if (define.type === 'bool') {
+        if (typeof value !== 'boolean') {
+            throw new Error(`Invalid define value for "${name}". bool define requires boolean value.`);
+        }
+        return {
+            type: 'bool',
+            value
+        };
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Invalid define value for "${name}". Numeric define must be finite.`);
+    }
+    if ((define.type === 'i32' || define.type === 'u32') && !Number.isInteger(value)) {
+        throw new Error(`Invalid define value for "${name}". ${define.type} define requires integer.`);
+    }
+    if (define.type === 'u32' && value < 0) {
+        throw new Error(`Invalid define value for "${name}". u32 define must be >= 0.`);
+    }
+    return {
+        type: define.type,
+        value
+    };
+}
+/**
+ * Validates and normalizes define entries.
+ */
+export function normalizeDefines(defines) {
+    const resolved = {};
+    for (const [name, value] of Object.entries(defines ?? {})) {
+        assertUniformName(name);
+        if (typeof value === 'boolean') {
+            resolved[name] = value;
+            continue;
+        }
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value)) {
+                throw new Error(`Invalid define value for "${name}". Define numbers must be finite.`);
+            }
+            resolved[name] = value;
+            continue;
+        }
+        const normalized = normalizeTypedDefine(name, value);
+        resolved[name] = Object.freeze({
+            type: normalized.type,
+            value: normalized.value
+        });
+    }
+    return resolved;
+}
+/**
+ * Validates include map identifiers and source chunks.
+ */
+export function normalizeIncludes(includes) {
+    const resolved = {};
+    for (const [name, source] of Object.entries(includes ?? {})) {
+        assertUniformName(name);
+        if (typeof source !== 'string' || source.trim().length === 0) {
+            throw new Error(`Invalid include "${name}". Include source must be a non-empty WGSL string.`);
+        }
+        resolved[name] = source;
+    }
+    return resolved;
+}
+/**
+ * Converts one define declaration to WGSL `const`.
+ */
+export function toDefineLine(key, value) {
+    if (typeof value === 'boolean') {
+        return `const ${key}: bool = ${value ? 'true' : 'false'};`;
+    }
+    if (typeof value === 'number') {
+        const valueLiteral = Number.isInteger(value) ? `${value}.0` : `${value}`;
+        return `const ${key}: f32 = ${valueLiteral};`;
+    }
+    if (value.type === 'bool') {
+        return `const ${key}: bool = ${value.value ? 'true' : 'false'};`;
+    }
+    if (value.type === 'f32') {
+        const numberValue = value.value;
+        const valueLiteral = Number.isInteger(numberValue) ? `${numberValue}.0` : `${numberValue}`;
+        return `const ${key}: f32 = ${valueLiteral};`;
+    }
+    if (value.type === 'i32') {
+        return `const ${key}: i32 = ${value.value};`;
+    }
+    return `const ${key}: u32 = ${value.value}u;`;
+}
+function expandChunk(source, kind, includeName, includes, stack) {
+    const sourceLines = source.split('\n');
+    const lines = [];
+    const mapEntries = [];
+    for (let index = 0; index < sourceLines.length; index += 1) {
+        const sourceLine = sourceLines[index];
+        if (sourceLine === undefined) {
+            continue;
+        }
+        const includeMatch = sourceLine.match(INCLUDE_DIRECTIVE_PATTERN);
+        if (!includeMatch) {
+            lines.push(sourceLine);
+            mapEntries.push({
+                kind,
+                line: index + 1,
+                ...(kind === 'include' && includeName ? { include: includeName } : {})
+            });
+            continue;
+        }
+        const includeKey = includeMatch[1];
+        if (!includeKey) {
+            throw new Error('Invalid include directive in fragment shader.');
+        }
+        assertUniformName(includeKey);
+        const includeSource = includes[includeKey];
+        if (!includeSource) {
+            throw new Error(`Unknown include "${includeKey}" referenced in fragment shader.`);
+        }
+        if (stack.includes(includeKey)) {
+            throw new Error(`Circular include detected for "${includeKey}". Include stack: ${[...stack, includeKey].join(' -> ')}.`);
+        }
+        const nested = expandChunk(includeSource, 'include', includeKey, includes, [
+            ...stack,
+            includeKey
+        ]);
+        lines.push(...nested.lines);
+        mapEntries.push(...nested.mapEntries);
+    }
+    return { lines, mapEntries };
+}
+/**
+ * Preprocesses material fragment with deterministic define/include expansion and line mapping.
+ */
+export function preprocessMaterialFragment(input) {
+    const normalizedDefines = normalizeDefines(input.defines);
+    const normalizedIncludes = normalizeIncludes(input.includes);
+    const fragmentExpanded = expandChunk(input.fragment, 'fragment', undefined, normalizedIncludes, []);
+    const defineEntries = Object.entries(normalizedDefines).sort(([a], [b]) => a.localeCompare(b));
+    const lines = [];
+    const defineLines = [];
+    const mapEntries = [];
+    for (let index = 0; index < defineEntries.length; index += 1) {
+        const entry = defineEntries[index];
+        if (!entry) {
+            continue;
+        }
+        const [name, value] = entry;
+        const defineLine = toDefineLine(name, value);
+        lines.push(defineLine);
+        defineLines.push(defineLine);
+        mapEntries.push({ kind: 'define', line: index + 1, define: name });
+    }
+    if (defineEntries.length > 0) {
+        lines.push('');
+        mapEntries.push(null);
+    }
+    lines.push(...fragmentExpanded.lines);
+    mapEntries.push(...fragmentExpanded.mapEntries);
+    const lineMap = [null, ...mapEntries];
+    return {
+        fragment: lines.join('\n'),
+        lineMap,
+        defineBlockSource: defineLines.join('\n')
+    };
+}