@downdraft/engine 0.1.1 → 0.2.0

package/dist/shader-graph/src/profiles.js

@@ -0,0 +1,305 @@
+// ============================================================================
+// Shader Graph Profile — configures the compiler for a specific render context
+// ============================================================================
+// Shader stage visibility flags — mirror GPUShaderStage values to avoid runtime WebGPU dependency
+const SHADER_STAGE = {
+    VERTEX: 0x1,
+    FRAGMENT: 0x2,
+    COMPUTE: 0x4,
+};
+// --- Built-in profiles ---
+export const SIMPLE_PROFILE = {
+    name: "simple",
+    chunks: [],
+    uniformFields: [
+        { name: "viewProj", type: "mat4x4<f32>" },
+        { name: "modelMatrix", type: "mat4x4<f32>" },
+        { name: "cameraPos", type: "vec3<f32>" },
+        { name: "time", type: "f32" },
+    ],
+    bindGroups: [
+        {
+            group: 0,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, type: "uniform" },
+                { binding: 1, visibility: SHADER_STAGE.FRAGMENT, type: "texture-2d", label: "albedoMap" },
+                { binding: 2, visibility: SHADER_STAGE.FRAGMENT, type: "sampler", label: "albedoSampler" },
+            ],
+        },
+    ],
+    vertexLayout: {
+        stride: 32,
+        attributes: [
+            { location: 0, name: "position", format: "float32x3", offset: 0 },
+            { location: 1, name: "normal", format: "float32x3", offset: 12 },
+            { location: 2, name: "uv", format: "float32x2", offset: 24 },
+        ],
+    },
+    instanced: false,
+    skinned: false,
+    outputFormat: "bgra8unorm",
+    depthFormat: "depth32float",
+    depthWriteEnabled: true,
+    blend: "opaque",
+    topology: "triangle-list",
+};
+export const PBR_PROFILE = {
+    name: "pbr",
+    chunks: ["pbr_lighting", "qrotate"],
+    uniformFields: [
+        { name: "viewProj", type: "mat4x4<f32>" },
+        { name: "cameraPos", type: "vec3<f32>" },
+        { name: "time", type: "f32" },
+        { name: "entityPos", type: "vec3<f32>" },
+        { name: "entityScale", type: "f32" },
+        { name: "entityRot", type: "vec4<f32>" },
+        { name: "entityType", type: "u32" },
+        { name: "entityFlags", type: "u32" },
+        { name: "wetness", type: "f32" },
+        { name: "_pad3", type: "f32" },
+        { name: "sunDirIntensity", type: "vec4<f32>" },
+        { name: "ambientParams", type: "vec4<f32>" },
+        { name: "fogColor", type: "vec4<f32>" },
+    ],
+    bindGroups: [
+        {
+            group: 0,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, type: "uniform" },
+            ],
+        },
+        {
+            group: 1,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "storage-read", label: "lightData", typeWgsl: "LightStorage" },
+            ],
+        },
+        {
+            group: 2,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "texture-2d", label: "brdfLUT" },
+                { binding: 1, visibility: SHADER_STAGE.FRAGMENT, type: "sampler", label: "brdfSampler" },
+            ],
+        },
+    ],
+    vertexLayout: {
+        stride: 24,
+        attributes: [
+            { location: 0, name: "position", format: "float32x3", offset: 0 },
+            { location: 1, name: "normal", format: "float32x3", offset: 12 },
+        ],
+    },
+    instanced: false,
+    skinned: false,
+    outputFormat: "bgra8unorm",
+    depthFormat: "depth32float",
+    depthWriteEnabled: true,
+    blend: "opaque",
+    topology: "triangle-list",
+};
+export const PBR_TEXTURED_PROFILE = {
+    ...PBR_PROFILE,
+    name: "pbr-textured",
+    vertexLayout: {
+        stride: 32,
+        attributes: [
+            { location: 0, name: "position", format: "float32x3", offset: 0 },
+            { location: 1, name: "normal", format: "float32x3", offset: 12 },
+            { location: 2, name: "uv", format: "float32x2", offset: 24 },
+        ],
+    },
+    bindGroups: [
+        {
+            group: 0,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, type: "uniform" },
+            ],
+        },
+        {
+            group: 1,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "storage-read", label: "lightData", typeWgsl: "LightStorage" },
+            ],
+        },
+        {
+            group: 2,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "texture-2d", label: "brdfLUT" },
+                { binding: 1, visibility: SHADER_STAGE.FRAGMENT, type: "sampler", label: "brdfSampler" },
+            ],
+        },
+        // Bindless material binding model (@group(3)): material SSBO + texture arrays.
+        // The host sets this bind group once per frame; per-draw material selection
+        // is via materialIndex in the uniform struct.
+        {
+            group: 3,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "storage-read", label: "bindlessMaterials" },
+            ],
+        },
+    ],
+};
+export const PBR_SKINNED_PROFILE = {
+    ...PBR_TEXTURED_PROFILE,
+    name: "pbr-skinned",
+    skinned: true,
+    maxBones: 256,
+    vertexLayout: {
+        stride: 72,
+        attributes: [
+            { location: 0, name: "position", format: "float32x3", offset: 0 },
+            { location: 1, name: "normal", format: "float32x3", offset: 12 },
+            { location: 2, name: "uv", format: "float32x2", offset: 24 },
+            { location: 3, name: "color", format: "float32x3", offset: 32 },
+            { location: 4, name: "joints", format: "uint32x4", offset: 48 },
+            { location: 5, name: "weights", format: "float32x4", offset: 64 },
+        ],
+    },
+    bindGroups: [
+        {
+            group: 0,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, type: "uniform" },
+                { binding: 3, visibility: SHADER_STAGE.VERTEX, type: "storage-read", label: "boneMatrices" },
+            ],
+        },
+        {
+            group: 1,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "storage-read", label: "lightData", typeWgsl: "LightStorage" },
+            ],
+        },
+        {
+            group: 2,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "texture-2d", label: "brdfLUT" },
+                { binding: 1, visibility: SHADER_STAGE.FRAGMENT, type: "sampler", label: "brdfSampler" },
+            ],
+        },
+        {
+            group: 3,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "storage-read", label: "bindlessMaterials" },
+            ],
+        },
+    ],
+};
+export const PBR_INSTANCED_PROFILE = {
+    name: "pbr-instanced",
+    chunks: ["dynamic_lights", "pbr_functions", "qrotate"],
+    uniformFields: [
+        { name: "viewProj", type: "mat4x4<f32>" },
+        { name: "cameraPos", type: "vec3<f32>" },
+        { name: "time", type: "f32" },
+        { name: "sunDirIntensity", type: "vec4<f32>" },
+        { name: "ambientParams", type: "vec4<f32>" },
+        { name: "fogColor", type: "vec4<f32>" },
+    ],
+    bindGroups: [
+        {
+            group: 0,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, type: "uniform" },
+                { binding: 1, visibility: SHADER_STAGE.VERTEX, type: "storage-read", label: "instances" },
+            ],
+        },
+        {
+            group: 1,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "storage-read", label: "lightData", typeWgsl: "LightStorage" },
+            ],
+        },
+        {
+            group: 2,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.FRAGMENT, type: "texture-2d", label: "brdfLUT" },
+                { binding: 1, visibility: SHADER_STAGE.FRAGMENT, type: "sampler", label: "brdfSampler" },
+            ],
+        },
+    ],
+    vertexLayout: {
+        stride: 24,
+        attributes: [
+            { location: 0, name: "position", format: "float32x3", offset: 0 },
+            { location: 1, name: "normal", format: "float32x3", offset: 12 },
+        ],
+    },
+    instanced: true,
+    skinned: false,
+    outputFormat: "bgra8unorm",
+    depthFormat: "depth32float",
+    depthWriteEnabled: true,
+    blend: "opaque",
+    topology: "triangle-list",
+};
+export const PBR_COLOR_VERTEX_PROFILE = {
+    ...PBR_PROFILE,
+    name: "pbr-color-vertex",
+    vertexLayout: {
+        stride: 36,
+        attributes: [
+            { location: 0, name: "position", format: "float32x3", offset: 0 },
+            { location: 1, name: "normal", format: "float32x3", offset: 12 },
+            { location: 2, name: "color", format: "float32x3", offset: 24 },
+        ],
+    },
+};
+// ============================================================================
+// GBUFFER_PROFILE — deferred rendering surface shader (multi-render-target)
+// ============================================================================
+// The graph compiles a *surface* shader that writes 4 GBuffer targets:
+//   @location(0) albedo (RGB) + AO (A)        — vec4
+//   @location(1) normal (RGB) + roughness (A) — vec4
+//   @location(2) metallic (R) + emissive (GBA)— vec4
+//   @location(3) velocity (screen-space motion)— vec2
+// The graph's output nodes use names: "albedo", "normal", "metallicEmissive",
+// "velocity". Lighting is applied in a separate deferred-lighting pass.
+export const GBUFFER_PROFILE = {
+    name: "gbuffer",
+    chunks: ["pbr_functions", "qrotate"],
+    uniformFields: [
+        { name: "viewProj", type: "mat4x4<f32>" },
+        { name: "prevViewProj", type: "mat4x4<f32>" },
+        { name: "modelMatrix", type: "mat4x4<f32>" },
+        { name: "prevModelMatrix", type: "mat4x4<f32>" },
+        { name: "cameraPos", type: "vec3<f32>" },
+        { name: "time", type: "f32" },
+    ],
+    bindGroups: [
+        {
+            group: 0,
+            entries: [
+                { binding: 0, visibility: SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, type: "uniform" },
+            ],
+        },
+    ],
+    vertexLayout: {
+        stride: 32,
+        attributes: [
+            { location: 0, name: "position", format: "float32x3", offset: 0 },
+            { location: 1, name: "normal", format: "float32x3", offset: 12 },
+            { location: 2, name: "uv", format: "float32x2", offset: 24 },
+        ],
+    },
+    instanced: false,
+    skinned: false,
+    outputFormat: "bgra8unorm", // ignored when outputFormats is set
+    outputFormats: ["bgra8unorm", "bgra8unorm", "bgra8unorm", "rg16float"],
+    outputNames: ["albedo", "normal", "metallicEmissive", "velocity"],
+    depthFormat: "depth32float",
+    depthWriteEnabled: true,
+    blend: "opaque",
+    topology: "triangle-list",
+};
+export const PROFILE_REGISTRY = {
+    simple: SIMPLE_PROFILE,
+    pbr: PBR_PROFILE,
+    "pbr-textured": PBR_TEXTURED_PROFILE,
+    "pbr-skinned": PBR_SKINNED_PROFILE,
+    "pbr-instanced": PBR_INSTANCED_PROFILE,
+    "pbr-color-vertex": PBR_COLOR_VERTEX_PROFILE,
+    "gbuffer": GBUFFER_PROFILE,
+};
+export function getProfile(name) {
+    return PROFILE_REGISTRY[name];
+}

package/dist/shader-graph/src/validator.js

@@ -0,0 +1,42 @@
+export class GraphValidator {
+    validate(graph) {
+        const errors = [];
+        const nodes = graph.getNodes();
+        const connections = graph.getConnections();
+        const nodeIds = new Set(nodes.map((n) => n.id));
+        for (let i = 0; i < connections.length; i++) {
+            const conn = connections[i];
+            if (!nodeIds.has(conn.from)) {
+                errors.push(`Connection from unknown node: ${conn.from}`);
+            }
+            if (!nodeIds.has(conn.to)) {
+                errors.push(`Connection to unknown node: ${conn.to}`);
+            }
+        }
+        const visited = new Set();
+        const visiting = new Set();
+        const checkCycle = (id) => {
+            if (visited.has(id))
+                return false;
+            if (visiting.has(id))
+                return true;
+            visiting.add(id);
+            for (let i = 0; i < connections.length; i++) {
+                if (connections[i].to === id) {
+                    if (checkCycle(connections[i].from))
+                        return true;
+                }
+            }
+            visiting.delete(id);
+            visited.add(id);
+            return false;
+        };
+        for (let i = 0; i < nodes.length; i++) {
+            if (checkCycle(nodes[i].id)) {
+                errors.push(`Cycle detected at node: ${nodes[i].id}`);
+                break;
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+}

package/dist/shader-graph/src/wgsl-binding-validator.js

@@ -0,0 +1,110 @@
+// ============================================================================
+// wgsl-binding-validator — duplicate @group/@binding var declaration detector
+//
+// Mirrors wgsl-struct-validator.ts. Parses `@group(N) @binding(M) var<...> name: type;`
+// declarations from a WGSL source string and flags duplicate (group, binding)
+// pairs. The compiler is the single emitter of bind-group declarations (sourced
+// from ShaderGraphProfile.bindGroups); chunks must NOT declare `@group/@binding
+// var` inline. This validator catches the regression where a chunk accidentally
+// re-declares a binding that the compiler also emits — a WGSL validation error
+// (duplicate `var` declaration) that the graph.spec.ts string-only tests miss
+// because they never call `device.createShaderModule`.
+//
+// In DOWNDRAFT_STRICT mode (or Vite dev mode) a duplicate throws; otherwise it
+// logs a warning. Comments (line `//...` and block `/* ... */`) are stripped
+// before parsing, same as wgsl-struct-validator.ts.
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+const log = createLogger("info");
+/**
+ * Parse all `@group(N) @binding(M) [var<...>] name: type;` declarations from a
+ * WGSL source string. Comments (line and block) are stripped first.
+ *
+ * Handles:
+ *   - `@group(0) @binding(0) var<uniform> uniforms: Uniforms;`
+ *   - `@group(1) @binding(0) var<storage, read> lightData: LightStorage;`
+ *   - `@group(2) @binding(0) var brdfLUT: texture_2d<f32>;`  (bare `var`)
+ *   - Multiple `@` attributes before `var` (e.g. `@location(0)` — though those
+ *     are on struct fields, not module-scope vars, they won't match the `var`
+ *     requirement and are safely skipped).
+ */
+export function parseWgslBindings(source) {
+    // Strip block comments.
+    let cleaned = source.replace(/\/\*[\s\S]*?\*\//g, "");
+    // Strip line comments.
+    cleaned = cleaned.replace(/\/\/[^\n]*/g, "");
+    const bindings = [];
+    // Match: @group(N) @binding(M) [var<access>] name: type;
+    // The `var<...>` part is optional in the sense that `var` may have no angle
+    // bracket (bare `var name: type;`). The access modifier inside the angle
+    // brackets can contain a comma (e.g. `storage, read`).
+    const bindingRegex = /@group\s*\(\s*(\d+)\s*\)\s*@binding\s*\(\s*(\d+)\s*\)\s*var(?:<([^>]*)>)?\s+(\w+)\s*:\s*([^;]+);/g;
+    let m;
+    while ((m = bindingRegex.exec(cleaned)) !== null) {
+        const group = Number(m[1]);
+        const binding = Number(m[2]);
+        const access = (m[3] ?? "").trim();
+        const name = m[4];
+        const typeWgsl = m[5].trim();
+        bindings.push({
+            group,
+            binding,
+            access,
+            name,
+            typeWgsl,
+            raw: m[0],
+        });
+    }
+    return bindings;
+}
+/**
+ * Find duplicate (group, binding) pairs in a list of parsed bindings.
+ * Returns one entry per duplicated pair, containing all declarations that
+ * share it. A pair with only one declaration is not a duplicate.
+ */
+export function findDuplicateBindings(parsed) {
+    const byKey = new Map();
+    parsed.forEach((b) => {
+        const key = `${b.group}:${b.binding}`;
+        let arr = byKey.get(key);
+        if (!arr) {
+            arr = [];
+            byKey.set(key, arr);
+        }
+        arr.push(b);
+    });
+    const dupes = [];
+    for (const [key, decls] of byKey.entries()) {
+        if (decls.length > 1) {
+            const [g, b] = key.split(":").map(Number);
+            dupes.push({ group: g, binding: b, declarations: decls });
+        }
+    }
+    // Sort by (group, binding) for deterministic output.
+    dupes.sort((a, b2) => (a.group - b2.group) || (a.binding - b2.binding));
+    return dupes;
+}
+/**
+ * Assert that a WGSL source string has no duplicate `@group/@binding var`
+ * declarations. In DOWNDRAFT_STRICT mode (env var = "1") or Vite dev mode,
+ * throws on duplicate. Otherwise logs a warning.
+ */
+export function assertNoDuplicateBindings(wgslSource) {
+    const parsed = parseWgslBindings(wgslSource);
+    const dupes = findDuplicateBindings(parsed);
+    if (dupes.length === 0)
+        return;
+    const lines = dupes.map((d) => {
+        const declLines = d.declarations.map((dec) => `    - @group(${dec.group}) @binding(${dec.binding}) var${dec.access ? `<${dec.access}>` : ""} ${dec.name}: ${dec.typeWgsl};`);
+        return `  @group(${d.group}) @binding(${d.binding}) declared ${d.declarations.length} times:\n${declLines.join("\n")}`;
+    });
+    const msg = `assertNoDuplicateBindings: duplicate @group/@binding var declarations:\n` +
+        lines.join("\n");
+    if (isStrict())
+        throw new Error(msg);
+    log.warn("wgsl-binding-validator", msg);
+}
+function isStrict() {
+    return (process?.env?.DOWNDRAFT_STRICT === "1" ||
+        (typeof import.meta !== "undefined" && import.meta.env?.DEV));
+}

package/dist/shader-graph/src/wgsl-struct-validator.js

@@ -0,0 +1,222 @@
+// ============================================================================
+// wgsl-struct-validator — drift detection between external .wgsl files and
+// WgslStruct definitions.
+//
+// For external .wgsl files (imported via ?raw) where we don't want to split the
+// struct out of the shader file, this parser extracts `struct Foo { ... }`
+// blocks from a WGSL source string, computes the layout, and compares it
+// against a WgslStruct definition. In DOWNDRAFT_STRICT mode a mismatch throws;
+// otherwise it logs a warning.
+//
+// Comments (line `//...` and block `slash-star ... star-slash`) are stripped.
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+import { wgsl } from "./wgsl-struct.js";
+const log = createLogger("info");
+/**
+ * Parse all `struct Name { ... }` blocks from a WGSL source string.
+ * Handles attributes on fields (e.g. `@location(0)`) and struct attributes.
+ * Comments are stripped first (line and block).
+ */
+export function parseWgslStructs(source) {
+    // Strip block comments.
+    let cleaned = source.replace(/\/\*[\s\S]*?\*\//g, "");
+    // Strip line comments.
+    cleaned = cleaned.replace(/\/\/[^\n]*/g, "");
+    const structs = [];
+    // Match: struct Name { fields }
+    // Fields may have attributes like @location(0) @builtin(position).
+    const structRegex = /struct\s+(\w+)\s*\{([^}]*)\}/g;
+    let m;
+    while ((m = structRegex.exec(cleaned)) !== null) {
+        const name = m[1];
+        const body = m[2];
+        const fields = parseStructBody(body);
+        structs.push({ name, fields });
+    }
+    return structs;
+}
+function parseStructBody(body) {
+    const fields = [];
+    // Split on commas (top-level — struct bodies here don't nest commas in
+    // practice; array sizes are numeric literals).
+    const parts = body.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    for (let _i = 0, _it = parts, _n = _it.length; _i < _n; _i++) {
+        const part = _it[_i];
+        // Strip leading attributes: @location(0), @builtin(x), @align(16), etc.
+        const stripped = part.replace(/@\w+(\([^)]*\))?/g, "").trim();
+        if (!stripped)
+            continue;
+        // Field: name: type
+        const colonIdx = stripped.indexOf(":");
+        if (colonIdx < 0)
+            continue;
+        const fieldName = stripped.slice(0, colonIdx).trim();
+        const typeWgsl = stripped.slice(colonIdx + 1).trim();
+        if (!fieldName || !typeWgsl)
+            continue;
+        fields.push({ name: fieldName, typeWgsl });
+    }
+    return fields;
+}
+// ─── WGSL type string → WgslType descriptor ─────────────────────────────────
+/** Map a WGSL type expression string to a WgslType descriptor. */
+export function wgslTypeFromString(typeWgsl) {
+    const t = typeWgsl.trim();
+    // Scalars
+    if (t === "f32")
+        return wgsl.f32;
+    if (t === "u32")
+        return wgsl.u32;
+    if (t === "i32")
+        return wgsl.i32;
+    if (t === "f16")
+        return wgsl.f16;
+    // Vectors: vecN<T>
+    const vecMatch = /^vec(\d)<(f32|f16|u32|i32)>$/.exec(t);
+    if (vecMatch) {
+        const n = Number(vecMatch[1]);
+        const el = vecMatch[2];
+        const isInt = el === "u32" || el === "i32";
+        if (n === 2)
+            return el === "f32" ? wgsl.vec2f : isInt ? (el === "u32" ? wgsl.vec2u : wgsl.vec2i) : wgsl.vec2f;
+        if (n === 3)
+            return el === "f32" ? wgsl.vec3f : isInt ? (el === "u32" ? wgsl.vec3u : wgsl.vec3i) : wgsl.vec3f;
+        if (n === 4)
+            return el === "f32" ? wgsl.vec4f : isInt ? (el === "u32" ? wgsl.vec4u : wgsl.vec4i) : wgsl.vec4f;
+    }
+    // Matrices: matCxR<T>
+    const matMatch = /^mat(\d)x(\d)<(f32|f16)>$/.exec(t);
+    if (matMatch) {
+        const c = Number(matMatch[1]);
+        const r = Number(matMatch[2]);
+        const el = matMatch[3];
+        if (el === "f32") {
+            if (c === 4 && r === 4)
+                return wgsl.mat4x4f;
+            if (c === 3 && r === 3)
+                return wgsl.mat3x3f;
+            if (c === 4 && r === 3)
+                return wgsl.mat4x3f;
+            if (c === 3 && r === 4)
+                return wgsl.mat3x4f;
+            if (c === 2 && r === 2)
+                return wgsl.mat2x2f;
+            if (c === 2 && r === 4)
+                return wgsl.mat2x4f;
+            if (c === 4 && r === 2)
+                return wgsl.mat4x2f;
+        }
+        throw new Error(`wgslTypeFromString: unsupported matrix ${t}`);
+    }
+    // Arrays: array<T, N> or array<T>
+    const arrMatch = /^array<(.+),\s*(\d+)>$/.exec(t);
+    if (arrMatch) {
+        const elType = wgslTypeFromString(arrMatch[1]);
+        const count = Number(arrMatch[2]);
+        return wgsl.array(elType, count);
+    }
+    const arrRuntimeMatch = /^array<(.+)>$/.exec(t);
+    if (arrRuntimeMatch) {
+        // Runtime-sized array — treat as 1 element for layout (the host sizes it).
+        const elType = wgslTypeFromString(arrRuntimeMatch[1]);
+        return wgsl.array(elType, 1);
+    }
+    throw new Error(`wgslTypeFromString: unrecognized type "${t}"`);
+}
+/**
+ * Compare a parsed WGSL struct against a WgslStruct definition.
+ * Returns a list of mismatch errors (empty if they match).
+ *
+ * Checks: field names (set equality), per-field type, per-field offset,
+ * struct size. Field ORDER is not enforced (WGSL layout is order-dependent,
+ * but if both sides compute layout from the same field order we get the same
+ * offsets — so we compare offsets, not order).
+ */
+export function compareStruct(parsed, def) {
+    const errors = [];
+    if (parsed.name !== def.name) {
+        errors.push(`struct name: wgsl "${parsed.name}" vs def "${def.name}"`);
+    }
+    // Build a layout from the parsed fields using the same rules.
+    let offset = 0;
+    let structAlign = 4;
+    const parsedLayout = [];
+    for (let _i = 0, _it = parsed.fields, _n = _it.length; _i < _n; _i++) {
+        const f = _it[_i];
+        let type;
+        try {
+            type = wgslTypeFromString(f.typeWgsl);
+        }
+        catch (e) {
+            errors.push(`field "${f.name}": cannot parse type "${f.typeWgsl}" (${e.message})`);
+            continue;
+        }
+        const align = type.align;
+        offset = (offset + align - 1) & ~(align - 1);
+        parsedLayout.push({ name: f.name, offset, type });
+        offset += type.size;
+        if (align > structAlign)
+            structAlign = align;
+    }
+    const parsedSize = (offset + structAlign - 1) & ~(structAlign - 1);
+    // Compare field sets.
+    const defNames = new Set(def.fieldMap.keys());
+    const parsedNames = new Set(parsed.fields.map((f) => f.name));
+    for (const n of defNames.values()) {
+        if (!parsedNames.has(n))
+            errors.push(`field "${n}" missing in wgsl`);
+    }
+    for (const n of parsedNames.values()) {
+        if (!defNames.has(n))
+            errors.push(`field "${n}" missing in def`);
+    }
+    // Compare offsets + types for shared fields.
+    for (let _i = 0, _it = parsedLayout, _n = _it.length; _i < _n; _i++) {
+        const pl = _it[_i];
+        const df = def.fieldMap.get(pl.name);
+        if (!df)
+            continue;
+        if (df.offset !== pl.offset) {
+            errors.push(`field "${pl.name}": offset wgsl ${pl.offset} vs def ${df.offset}`);
+        }
+        if (df.type.wgsl !== pl.type.wgsl) {
+            errors.push(`field "${pl.name}": type wgsl "${pl.type.wgsl}" vs def "${df.type.wgsl}"`);
+        }
+    }
+    if (parsedSize !== def.size) {
+        errors.push(`struct size: wgsl ${parsedSize} vs def ${def.size}`);
+    }
+    return { structName: parsed.name, errors };
+}
+/**
+ * Assert that a WgslStruct definition matches the corresponding struct in a
+ * WGSL source string. In DOWNDRAFT_STRICT mode (env var = "1"), throws on
+ * mismatch. Otherwise logs a warning.
+ *
+ * @param wgslSource Raw WGSL source (e.g. imported via `?raw`).
+ * @param def The WgslStruct definition to compare against.
+ */
+export function assertWgslStructMatches(wgslSource, def) {
+    const parsed = parseWgslStructs(wgslSource);
+    const match = parsed.find((s) => s.name === def.name);
+    if (!match) {
+        const msg = `assertWgslStructMatches: struct "${def.name}" not found in WGSL source`;
+        if (isStrict())
+            throw new Error(msg);
+        log.warn("wgsl-struct-validator", msg);
+        return;
+    }
+    const result = compareStruct(match, def);
+    if (result.errors.length > 0) {
+        const msg = `assertWgslStructMatches: struct "${def.name}" drift:\n` +
+            result.errors.map((e) => `  - ${e}`).join("\n");
+        if (isStrict())
+            throw new Error(msg);
+        log.warn("wgsl-struct-validator", msg);
+    }
+}
+function isStrict() {
+    return (process?.env?.DOWNDRAFT_STRICT === "1" ||
+        (typeof import.meta !== "undefined" && import.meta.env?.DEV));
+}