@woosh/meep-engine 3.37.0 → 3.39.0

package/src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js

@@ -71,10 +71,62 @@ class Scope {
         this.parent = parent;
         /** @type {Map<string, WgslType>} */
         this.symbols = new Map();
+        /**
+         * Names declared in this scope that are pointers. The type recorded for one is its
+         * pointee's, which is how every use but the pointer's own reads it.
+         * @type {Set<string>}
+         */
+        this.pointers = new Set();
+        /**
+         * The pointers among them that are pointers to a scalar, held in a `{ value }` box — see
+         * {@link declarePointer}.
+         * @type {Set<string>}
+         */
+        this.boxed = new Set();
     }
 
     declare(name, type) {
         this.symbols.set(name, type || T_UNKNOWN);
+        this.pointers.delete(name);
+        this.boxed.delete(name);
+    }
+
+    /**
+     * Declare a pointer. One to a vector, matrix, array or struct is the pointee's own object, so a
+     * write through it lands. One to a scalar cannot be — a JavaScript number has no identity to
+     * write through — so a pointer-to-scalar parameter travels as a `{ value }` box instead:
+     * `*p` reads and writes `p.value`, and a call handing over `&x` copies the box back into
+     * `x` when it returns.
+     *
+     * @param {string} name
+     * @param {WgslType} type the pointee's
+     * @param {boolean} boxed
+     */
+    declarePointer(name, type, boxed) {
+        this.symbols.set(name, type || T_UNKNOWN);
+        this.pointers.add(name);
+        if (boxed) this.boxed.add(name);
+        else this.boxed.delete(name);
+    }
+
+    /**
+     * @param {string} name
+     * @returns {boolean} whether `name`, as seen from here, is a pointer
+     */
+    isPointer(name) {
+        if (this.symbols.has(name)) return this.pointers.has(name);
+        if (this.parent) return this.parent.isPointer(name);
+        return false;
+    }
+
+    /**
+     * @param {string} name
+     * @returns {boolean} whether `name`, as seen from here, is a boxed pointer to a scalar
+     */
+    isBoxedPointer(name) {
+        if (this.symbols.has(name)) return this.boxed.has(name);
+        if (this.parent) return this.parent.isBoxedPointer(name);
+        return false;
     }
 
     /** @returns {WgslType} */
@@ -493,9 +545,16 @@ class Compiler {
         /** @type {Map<string, { name: string, fields: Array<{ name: string, type: WgslType }> }>} */
         this.structs = new Map();
 
-        /** @type {Map<string, { name: string, returnType: WgslType, params: Array<{ name: string, type: WgslType }> }>} */
+        /**
+         * `pointer` marks a pointer parameter and `boxed` one to a scalar — see
+         * {@link Scope#declarePointer}.
+         * @type {Map<string, { name: string, returnType: WgslType, params: Array<{ name: string, type: WgslType, pointer: boolean, boxed: boolean }> }>}
+         */
         this.functions = new Map();
 
+        /** Numbers the boxes a call site makes for `&x` arguments, so nested calls cannot collide. */
+        this.box_counter = 0;
+
         /** @type {Array<{ name: string, type: WgslType, group: number, binding: number, addressSpace: string | null, accessMode: string | null }>} */
         this.globalBindings = [];
 
@@ -833,7 +892,7 @@ function collectFunction(c, node) {
     const name = ident.text;
 
     const param_list_node = namedChildByType(header, 'param_list');
-    /** @type {Array<{ name: string, type: WgslType, builtin: string | null }>} */
+    /** @type {Array<{ name: string, type: WgslType, builtin: string | null, pointer: boolean, boxed: boolean }>} */
     const params = [];
     if (param_list_node !== null) {
         const param_nodes = namedChildrenByType(param_list_node, 'param');
@@ -841,10 +900,15 @@ function collectFunction(c, node) {
             const p_ident = namedChildByType(p, 'ident');
             const p_type = namedChildByType(p, 'type_specifier');
             const builtin = extractBuiltin(p);
+            // parseTypeSpecifier peels a pointer down to its pointee, so ask the text
+            const type = parseTypeSpecifier(p_type);
+            const is_pointer = p_type !== null && /^ptr\s*</.test(p_type.text.trim());
             params.push({
                 name: p_ident.text,
-                type: parseTypeSpecifier(p_type),
+                type,
                 builtin,
+                pointer: is_pointer,
+                boxed: is_pointer && type.kind === 'primitive',
             });
         }
     }
@@ -857,7 +921,7 @@ function collectFunction(c, node) {
         }
     }
 
-    c.functions.set(name, { name, returnType, params: params.map(p => ({ name: p.name, type: p.type })) });
+    c.functions.set(name, { name, returnType, params: params.map(p => ({ name: p.name, type: p.type, pointer: p.pointer, boxed: p.boxed })) });
 
     // Detect the entry attribute (@compute, @fragment, or @vertex) and capture stage-specific
     // metadata. The emulator supports compute and fragment entries; vertex is rejected because
@@ -923,7 +987,18 @@ function emitFunction(c, node) {
 
     c.scope = c.scope.push();
     for (let i = 0; i < param_nodes.length; i++) {
-        c.scope.declare(param_names[i], info.params[i].type);
+        if (info.params[i].pointer) {
+            c.scope.declarePointer(param_names[i], info.params[i].type, info.params[i].boxed);
+        } else {
+            c.scope.declare(param_names[i], info.params[i].type);
+        }
+
+        if (info.params[i].boxed) {
+            // A WGSL caller hands over a box. One from JavaScript may hand over a bare number, and
+            // can read nothing back from it, but the callee still reads its own writes.
+            const js = identToJs(param_names[i]);
+            c.out.add(`if (typeof ${js} !== 'object' || ${js} === null) { ${js} = { value: ${js} }; }`);
+        }
     }
 
     const body = namedChildByType(node, 'compound_statement');
@@ -1314,8 +1389,16 @@ function emitVariableOrValueStatement(c, node) {
         if (type === T_UNKNOWN || type.kind === 'unknown') {
             type = keeps_abstract ? expr.type : concreteDefault(expr.type);
         }
-        c.scope.declare(name, type);
-        c.out.add(`${kind} ${identToJs(name)} = ${expr.code};`);
+        // A `var` is storage of its own. A `let` cannot be written through, but the variable it
+        // was read from can, so one read straight off a variable takes a copy too — unless it is a
+        // pointer, which is the variable rather than a read of it.
+        const value = var_decl !== null || isReferenceExpression(c, expr_node) ? ownedValueCode(expr) : expr.code;
+        if (var_decl === null && isPointerExpression(c, expr_node)) {
+            c.scope.declarePointer(name, type, false);
+        } else {
+            c.scope.declare(name, type);
+        }
+        c.out.add(`${kind} ${identToJs(name)} = ${value};`);
     } else {
         c.scope.declare(name, type);
         c.out.add(`${kind} ${identToJs(name)} = ${defaultValueForType(type)};`);
@@ -1378,7 +1461,7 @@ function emitVariableUpdatingStatement(c, node) {
         const rhs_compiled = compileExpression(c, expr);
 
         if (op_text === '=' || op_text === '') {
-            c.out.add(emitWriteStatement(lhs_compiled, rhs_compiled.code));
+            c.out.add(emitWriteStatement(lhs_compiled, ownedValueCode(rhs_compiled)));
             return;
         }
 
@@ -1423,6 +1506,89 @@ function emitVariableUpdatingStatement(c, node) {
     c.error(inner, `unsupported variable_updating_statement: ${inner.type}`);
 }
 
+/**
+ * Whether an expression reads a variable, or part of one — `v`, `s.field`, `a[i]`, `*p` —
+ * rather than computing a fresh value. Only such an expression can hand over an object something
+ * else may still write to. A pointer named on its own is not a read: it is the variable.
+ *
+ * @param {Compiler} c
+ * @param {Node} node
+ * @returns {boolean}
+ */
+function isReferenceExpression(c, node) {
+    const u = unwrapExpression(node);
+
+    switch (u.type) {
+        case 'ident':
+            return !c.scope.isPointer(u.text);
+        case 'template_elaborated_ident': {
+            const ident = namedChildByType(u, 'ident');
+            return !c.scope.isPointer(ident !== null ? ident.text : u.text);
+        }
+        case 'unary_expression':
+            return textBeforeFirstNamed(u).trim() === '*';
+        case 'paren_expression':
+            return isReferenceExpression(c, namedChildByType(u, 'expression'));
+        case 'singular_expression':
+            // with an access on it, a pointer is read through rather than named
+            return u.namedChildren.length > 1 || isReferenceExpression(c, u.namedChildren[0]);
+        default:
+            return false;
+    }
+}
+
+/**
+ * Whether an expression is a pointer: `&x`, or a pointer named on its own.
+ *
+ * @param {Compiler} c
+ * @param {Node} node
+ * @returns {boolean}
+ */
+function isPointerExpression(c, node) {
+    const u = unwrapExpression(node);
+
+    switch (u.type) {
+        case 'ident':
+            return c.scope.isPointer(u.text);
+        case 'template_elaborated_ident': {
+            const ident = namedChildByType(u, 'ident');
+            return c.scope.isPointer(ident !== null ? ident.text : u.text);
+        }
+        case 'unary_expression':
+            return textBeforeFirstNamed(u).trim() === '&';
+        case 'paren_expression':
+            return isPointerExpression(c, namedChildByType(u, 'expression'));
+        case 'singular_expression':
+            return u.namedChildren.length === 1 && isPointerExpression(c, u.namedChildren[0]);
+        default:
+            return false;
+    }
+}
+
+/**
+ * The code for a value about to be stored: wrapped in `wgsl.copy` unless its type is one the
+ * emulator holds as an immutable JavaScript value.
+ *
+ * A value of unknown type is copied too; `wgsl.copy` hands a number straight back.
+ *
+ * @param {{code: string, type: WgslType}} compiled
+ * @returns {string}
+ */
+function ownedValueCode(compiled) {
+    const kind = compiled.type === undefined || compiled.type === null ? 'unknown' : compiled.type.kind;
+
+    switch (kind) {
+        case 'primitive':
+        case 'abstract':
+        case 'atomic':
+        case 'texture_2d':
+        case 'sampler':
+            return compiled.code;
+        default:
+            return `wgsl.copy(${compiled.code})`;
+    }
+}
+
 /**
  * Emit a write to an LHS. Most LHS expressions are plain JS LValues (`x`, `arr[i]`, `obj.f`) and
  * are written with `=`. Mat-column LHS — `m[i]` for a mat — is special: the compiler emits it as
@@ -1455,7 +1621,8 @@ function emitReturnStatement(c, node) {
         c.out.add('return;');
     } else {
         const e = compileExpression(c, expr);
-        c.out.add(`return ${e.code};`);
+        // a parameter or a global handed straight back would otherwise reach the caller as itself
+        c.out.add(`return ${isReferenceExpression(c, expr) ? ownedValueCode(e) : e.code};`);
     }
 }
 
@@ -1571,7 +1738,9 @@ function emitForInitInline(c, node) {
             type = concreteDefault(init.type);
         }
         c.scope.declare(name, type);
-        const value = init !== null ? init.code : defaultValueForType(type);
+        const value = init === null
+            ? defaultValueForType(type)
+            : var_decl !== null ? ownedValueCode(init) : init.code;
         // `var i = …` (mutable, common in `for (var i = 0; ...; i = i + 1)`) → JS `let`.
         // `let i = …` / `const i = …` (immutable) → JS `const`.
         const kind = var_decl !== null ? 'let' : 'const';
@@ -1602,9 +1771,9 @@ function emitForUpdateInline(c, node) {
             const rhs_compiled = compileExpression(c, expr);
             if (op_text === '=' || op_text === '') {
                 if (lhs_compiled.through_pointer === true) {
-                    return `${lhs_compiled.code} = wgsl.store_ptr(${lhs_compiled.code}, ${rhs_compiled.code})`;
+                    return `${lhs_compiled.code} = wgsl.store_ptr(${lhs_compiled.code}, ${ownedValueCode(rhs_compiled)})`;
                 }
-                return `${lhs_compiled.code} = ${rhs_compiled.code}`;
+                return `${lhs_compiled.code} = ${ownedValueCode(rhs_compiled)}`;
             }
             const arith = { '+=': 'add', '-=': 'sub', '*=': 'mul', '/=': 'div', '%=': 'rem' };
             if (arith.hasOwnProperty(op_text)) {
@@ -1869,7 +2038,7 @@ function compileExpressionAbstract(c, node) {
     if (u.type === 'paren_expression') {
         const inner = namedChildByType(u, 'expression');
         const e = compileExpressionAbstract(c, inner);
-        return { code: `(${e.code})`, type: e.type, value: e.value };
+        return { code: `(${e.code})`, type: e.type, value: e.value, pointer_box: e.pointer_box };
     }
     if (u.type === 'call_expression') {
         const call_phrase = namedChildByType(u, 'call_phrase');
@@ -1878,10 +2047,10 @@ function compileExpressionAbstract(c, node) {
     if (u.type === 'template_elaborated_ident') {
         const ident = namedChildByType(u, 'ident');
         const name = ident !== null ? ident.text : u.text;
-        return { code: identToJs(name), type: c.scope.lookup(name) };
+        return { code: identToJs(name), type: c.scope.lookup(name), pointer_box: c.scope.isBoxedPointer(name) };
     }
     if (u.type === 'ident') {
-        return { code: identToJs(u.text), type: c.scope.lookup(u.text) };
+        return { code: identToJs(u.text), type: c.scope.lookup(u.text), pointer_box: c.scope.isBoxedPointer(u.text) };
     }
 
     c.error(u, `unsupported expression: ${u.type}`);
@@ -2294,6 +2463,7 @@ function compileUnaryExpression(c, node) {
     }
     if (prefix === '!') return { code: `!${operand.code}`, type: operand.type };
     if (prefix === '~') return { code: `wgsl.not(${operand.code})`, type: operand.type };
+    if (prefix === '*' && operand.pointer_box === true) return { code: `${operand.code}.value`, type: operand.type };
     if (prefix === '*' || prefix === '&') return { code: operand.code, type: operand.type };
 
     return { code: `${prefix}${operand.code}`, type: operand.type };
@@ -2317,9 +2487,14 @@ function compileSingularExpression(c, node) {
         type = next.type;
     }
 
-    // a bare literal reached through a singular expression is still a literal; anything with an
-    // access specifier on it is not one
-    return { code, type, value: named.length === 1 ? head_result.value : undefined };
+    // a bare literal reached through a singular expression is still a literal, and a bare boxed
+    // pointer still a box; anything with an access specifier on it is neither
+    return {
+        code,
+        type,
+        value: named.length === 1 ? head_result.value : undefined,
+        pointer_box: named.length === 1 ? head_result.pointer_box : undefined,
+    };
 }
 
 /**
@@ -2426,10 +2601,13 @@ function compileCallPhraseTyped(c, node) {
 
     /** @type {Array<{ code: string, type: WgslType }>} */
     let arg_results = [];
+    /** @type {Node[]} */
+    const arg_nodes = [];
     if (arg_list !== null) {
         const comma_list = namedChildByType(arg_list, 'expression_comma_list');
         if (comma_list !== null) {
             for (const arg of namedChildrenByType(comma_list, 'expression')) {
+                arg_nodes.push(arg);
                 arg_results.push(compileExpressionAbstract(c, arg));
             }
         }
@@ -2543,9 +2721,13 @@ function compileCallPhraseTyped(c, node) {
         };
     }
 
+    // An array or a struct stores its arguments, so one read straight off a variable goes in as a
+    // copy, as it would into a `var`.
+    const stored_args = arg_results.map((a, i) => isReferenceExpression(c, arg_nodes[i]) ? ownedValueCode(a) : a.code);
+
     // 6) array / array<T, N> constructor.
     if (callee_name === 'array') {
-        return { code: `[${args.join(', ')}]`, type: T_UNKNOWN };
+        return { code: `[${stored_args.join(', ')}]`, type: T_UNKNOWN };
     }
 
     // 7) Struct constructor.
@@ -2553,7 +2735,7 @@ function compileCallPhraseTyped(c, node) {
         const info = c.structs.get(callee_name);
         const parts = [`(() => { const __s__ = new ${identToJs(callee_name)}();`];
         for (let i = 0; i < info.fields.length && i < args.length; i++) {
-            parts.push(`__s__.${info.fields[i].name} = ${args[i]};`);
+            parts.push(`__s__.${info.fields[i].name} = ${stored_args[i]};`);
         }
         parts.push(`return __s__; })()`);
         return { code: parts.join(' '), type: { kind: 'struct', name: callee_name } };
@@ -2561,9 +2743,39 @@ function compileCallPhraseTyped(c, node) {
 
     // 8) User-defined function.
     if (c.functions.has(callee_name)) {
+        const info = c.functions.get(callee_name);
+
+        // `&x` for a pointer-to-scalar parameter: `&x` compiled to `x`'s own code, which is
+        // assignable, so x goes in as a box and the box's value comes back out into x. A boxed
+        // parameter handed on as it is (`f(p)`) is already the caller's box.
+        const boxes = [];
+        const call_args = args.slice();
+
+        for (let i = 0; i < arg_nodes.length && i < info.params.length; i++) {
+            if (info.params[i].boxed !== true) continue;
+
+            const arg = unwrapExpression(arg_nodes[i]);
+
+            if (arg.type !== 'unary_expression' || textBeforeFirstNamed(arg).trim() !== '&') continue;
+
+            const box = `__box_${c.box_counter++}__`;
+
+            boxes.push({ box, target: args[i] });
+            call_args[i] = box;
+        }
+
+        const call = `${identToJs(callee_name)}(${call_args.join(', ')})`;
+
+        if (boxes.length === 0) {
+            return { code: call, type: info.returnType };
+        }
+
+        const fill = boxes.map(b => `const ${b.box} = { value: ${b.target} };`).join(' ');
+        const drain = boxes.map(b => `${b.target} = ${b.box}.value;`).join(' ');
+
         return {
-            code: `${identToJs(callee_name)}(${args.join(', ')})`,
-            type: c.functions.get(callee_name).returnType,
+            code: `(() => { ${fill} const __result__ = ${call}; ${drain} return __result__; })()`,
+            type: info.returnType,
         };
     }
 
@@ -2651,6 +2863,10 @@ function inferBuiltinReturnType(name, args) {
             ? args[0].type
             : { kind: 'vec', size: 3, scalar: 'f32' };
     }
+    if (name === 'refract') {
+        // the incident vector's type; the third argument is the scalar ratio of indices
+        return commonArgumentType(args.slice(0, 2));
+    }
     if (name === 'all' || name === 'any') return { kind: 'primitive', name: 'bool' };
     if (name === 'select') {
         // the two values; the third argument is the condition
@@ -2713,6 +2929,11 @@ function compileLhs(c, node) {
                 child => child.type === 'component_or_swizzle_specifier'
             );
 
+            if (prefix === '*' && inner.pointer_box === true && !selects_part) {
+                // a pointer to a scalar is a box, and the store goes into it
+                return { code: `${inner.code}.value`, type: inner.type };
+            }
+
             return {
                 ...inner,
                 through_pointer: prefix === '*' && !selects_part,
@@ -2723,11 +2944,13 @@ function compileLhs(c, node) {
     const core = namedChildByType(node, 'core_lhs_expression');
     let code;
     let type;
+    let pointer_box = false;
     if (core !== null) {
         const ident = namedChildByType(core, 'ident');
         if (ident !== null) {
             code = identToJs(ident.text);
             type = c.scope.lookup(ident.text);
+            pointer_box = c.scope.isBoxedPointer(ident.text);
         } else {
             const nested = namedChildByType(core, 'lhs_expression');
             if (nested !== null) {
@@ -2749,7 +2972,8 @@ function compileLhs(c, node) {
             const next = applyAccessSpecifier(c, child, code, type);
             code = next.code;
             type = next.type;
+            pointer_box = false;
         }
     }
-    return { code, type };
+    return { code, type, pointer_box };
 }

package/src/shade/wgsl/emulator/WGSLLanguageCore.d.ts

@@ -1,15 +1,19 @@
-/**
- * The default WGSL language core — the `wgsl` object passed into the generated JS.
- *
- * Provides:
- * - vector / matrix constructors (`vec3f`, `vec2u`, etc.)
- * - scalar constructors / casts (`f32`, `i32`, `u32`, `bool`)
- * - arithmetic helpers (`add`, `sub`, `mul`, `div`, `mod`, `neg`)
- * - WGSL builtins (`mix`, `clamp`, `min`, `max`, `abs`, `floor`, `ceil`, `pow`, ...)
- * - texture intrinsics (`textureLoad`, `textureSampleLevel`)
- * - control flow helpers (`workgroupBarrier`, `storageBarrier`)
- *
- * @type {object}
- */
-export const WGSLLanguageCore: object;
+export namespace WGSLLanguageCore {
+    /**
+     * Bit-cast (WGSL `bitcast`). Reinterprets a value's bit pattern as a different type.
+     *
+     * JS has no separate u32/i32/f32 scalar types — they're all `number` — so the source type
+     * cannot be detected from the value at runtime. The compiler passes it explicitly when known;
+     * otherwise we fall back to a heuristic: integer-targeted casts assume f32 source, float-targeted
+     * casts assume u32 source (the common "interpret bit pattern as float" idiom).
+     *
+     * For typed-array (vector) inputs the source type is auto-detected from the array constructor.
+     *
+     * @param {*} v
+     * @param {string} target — destination type name, e.g. `'f32'` / `'u32'` / `'i32'`
+     * @param {string} [source] — source type name; required for unambiguous scalar casts
+     * @returns {number | TypedArray}
+     */
+    function bitcast(v: any, target: string, source?: string): any;
+}
 //# sourceMappingURL=WGSLLanguageCore.d.ts.map

package/src/shade/wgsl/emulator/WGSLLanguageCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":"AAkRA;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAwpCd"}
+{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":";IA8+CA;;;;;;;;;;;;;;OAcG;IACH,+DAmDC"}

package/src/shade/wgsl/emulator/WGSLLanguageCore.js

@@ -285,6 +285,36 @@ function ternop(a, b, c, op) {
  *
  * @type {object}
  */
+/**
+ * A vector, matrix, array or struct as storage of its own: typed arrays and arrays element by
+ * element, structs field by field and keeping their class. Anything else is immutable here and
+ * comes back as it is.
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+function copy_value(value) {
+    if (ArrayBuffer.isView(value)) {
+        return value.slice();
+    }
+
+    if (Array.isArray(value)) {
+        return value.map(copy_value);
+    }
+
+    if (value !== null && typeof value === 'object') {
+        const result = Object.create(Object.getPrototypeOf(value));
+
+        for (const key of Object.keys(value)) {
+            result[key] = copy_value(value[key]);
+        }
+
+        return result;
+    }
+
+    return value;
+}
+
 export const WGSLLanguageCore = {
     // ---------------------------------------------------------------------
     // Scalar casts
@@ -388,12 +418,9 @@ export const WGSLLanguageCore = {
      * a hit the traversal keeps and shades.
      *
      * Vectors, matrices and structs are objects, so the store goes through the reference and the
-     * caller sees it. **A pointer to a scalar still cannot**: a JavaScript number has no identity
-     * to write through, so the rebind is all there is, and a caller passing `&some_f32` sees its
-     * variable unchanged. Within the callee the value is right — `*p` reads back what `*p = …`
-     * wrote — so the in-out scalar accumulators in `sample_discrete_wrs_*` behave, and only a
-     * result handed *out* through a scalar pointer is lost. Widen such an out-parameter to a
-     * vector or a struct, or return it, if a test needs to see it.
+     * caller sees it. A pointer to a scalar never gets here: a JavaScript number has no identity to
+     * write through, so the compiler hands one over as a `{ value }` box, stores into `p.value`,
+     * and copies the box back into the caller's variable when the call returns.
      *
      * @param {Float32Array|Float16Array|Uint32Array|Int32Array|Array|object|number|boolean} target
      * @param {ArrayLike<number>|object|number|boolean} value
@@ -417,6 +444,21 @@ export const WGSLLanguageCore = {
         return value;
     },
 
+    /**
+     * The value about to be stored into a `var`, a member or an element, as storage of its own.
+     *
+     * WGSL has no references: `var b = a;` and `b = a;` both copy. Vectors, matrices, arrays and
+     * structs are objects here, so storing the object itself leaves two names on one value, and a
+     * write through either shows through the other — including back into a caller, whose argument
+     * arrives as the same object.
+     *
+     * @param {*} value
+     * @returns {*}
+     */
+    copy(value) {
+        return copy_value(value);
+    },
+
     /**
      * Determinant of a square matrix stored as a flat column-major typed array.
      * Supports the WGSL square-matrix sizes: 2x2, 3x3, 4x4.
@@ -767,6 +809,16 @@ export const WGSLLanguageCore = {
         return out;
     },
 
+    refract(i, n, eta) {
+        const d = WGSLLanguageCore.dot(n, i);
+        const k = 1 - eta * eta * (1 - d * d);
+        const out = new i.constructor(i.length);
+        if (k < 0) { out.fill(0); return out; }
+        const normal_scale = eta * d + Math.sqrt(k);
+        for (let j = 0; j < i.length; j++) out[j] = eta * i[j] - normal_scale * n[j];
+        return out;
+    },
+
     // ---------------------------------------------------------------------
     // Matrix × {matrix, vector} and vector × matrix products.
     //
@@ -1226,6 +1278,9 @@ export const WGSLLanguageCore = {
         t.write(x, y, z, value);
     },
 
+    // CPUBitmapData models one stored mip level.
+    textureNumLevels(_t) { return 1; },
+
     /**
      * `textureDimensions(t, level) -> u32 | vec2<u32> | vec3<u32>`
      *

package/src/shade/renderer/animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.d.ts

@@ -1,29 +0,0 @@
-/**
- * Per-element f32 atomic min/max via CAS-spin over a `atomic<u32>`
- * storage cell, bitcast through f32 for comparison.
- *
- * WGSL has native u32/i32 atomics only. For float min/max the
- * sign-bit-flip encoding (cheaper, only `atomicMin`/`atomicMax`
- * needed) is a tempting alternative, but it leaves the buffer in
- * "encoded" form during the dispatch chain — readers in the same
- * frame would need to know whether the value is encoded or decoded.
- * The CAS-spin keeps the storage in plain f32 the whole time, which
- * matches what the rasterizer's meshlet-culling shader already
- * expects in `meshlet.bounds_box`.
- *
- * Contention model: every contributor reads → compares → conditionally
- * writes. When the existing value already bounds the contribution
- * (typical for late contributors as the box settles), the comparison
- * exits early without any CAS. The worst case is many threads
- * hammering the same slot in the first few iterations; the loop is
- * bounded by collisions, not by thread count.
- *
- * `value` is treated as a normal f32 — NaNs are not handled (vertex
- * positions are never NaN in correctly-loaded geometry). +inf / -inf
- * are valid (they're our scatter sentinels).
- *
- * @type {CodeChunk}
- */
-export const chunk_aabb_atomic_f32: CodeChunk;
-import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
-//# sourceMappingURL=chunk_aabb_atomic_f32.d.ts.map

package/src/shade/renderer/animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk_aabb_atomic_f32.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,oCAFU,SAAS,CAgChB;0BA1DuB,uCAAuC"}

package/src/shade/renderer/shader/chunk/geometry/plane/plane_ray_raycast.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"plane_ray_raycast.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/plane/plane_ray_raycast.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,gCAFU,SAAS,CA2Cf;0BA/CsB,gCAAgC"}

package/src/shade/renderer/shadow/map/csm/CSM_CASTER_RANGE_STRUCT.d.ts

@@ -1,29 +0,0 @@
-/**
- * What the caster-range pass publishes for one directional shadow map: per cascade, how near
- * along the light's axis the nearest shadow caster inside the cascade's side planes reaches.
- *
- * A row of the light database's `shadow_csm_caster_range` table, written on the GPU by
- * `shader_csm_caster_range_publish` and read back to the CPU, which fits the next frame's cascade
- * near plane to it. The CPU writes it once, at {@link CSM_CASTER_RANGE_UNKNOWN}, when the row is
- * claimed; a cascade nothing was measured for keeps that value, and a reader treats it as "no
- * caster".
- *
- * @type {WebGPUStruct}
- */
-export const CSM_CASTER_RANGE_STRUCT: WebGPUStruct;
-/**
- * The largest finite f32: what a cascade's slot holds before anything is merged into it, and after
- * the publish reset it. Not +inf, because WGSL will not const-fold `bitcast<f32>(0x7F800000u)`;
- * no world coordinate comes within orders of magnitude of it.
- *
- * @type {number}
- */
-export const CSM_CASTER_RANGE_UNKNOWN: number;
-/**
- * {@link CSM_CASTER_RANGE_UNKNOWN} as the u32 bit pattern a scratch word is seeded with.
- *
- * @type {number}
- */
-export const CSM_CASTER_RANGE_UNKNOWN_BITS: number;
-import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
-//# sourceMappingURL=CSM_CASTER_RANGE_STRUCT.d.ts.map

package/src/shade/renderer/shadow/map/csm/CSM_CASTER_RANGE_STRUCT.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CSM_CASTER_RANGE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/csm/CSM_CASTER_RANGE_STRUCT.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AACH,sCAFU,YAAY,CAUM;AAE5B;;;;;;GAMG;AACH,uCAFU,MAAM,CAEoC;AAEpD;;;;GAIG;AACH,4CAFU,MAAM,CAEwC;6BAvC3B,sCAAsC"}