typegpu 0.11.9 → 0.12.1

package/core/querySet/querySet.js

@@ -1,106 +1,130 @@
-import { $internal } from "../../shared/symbols.js";
 import { setName } from "../../shared/meta.js";
-
-//#region src/core/querySet/querySet.ts
-function INTERNAL_createQuerySet(group, type, count, rawQuerySet) {
-	return new TgpuQuerySetImpl(group, type, count, rawQuerySet);
+import { $internal, $soul } from "../../shared/symbols.js";
+export function INTERNAL_createQuerySet(group, type, count, rawQuerySet) {
+    return new TgpuQuerySetImpl(group, type, count, rawQuerySet);
 }
-function isQuerySet(value) {
-	const maybe = value;
-	return maybe?.resourceType === "query-set" && !!maybe[$internal];
+export function isQuerySet(value) {
+    const maybe = value;
+    return maybe?.resourceType === 'query-set' && !!maybe[$internal];
+}
+class TgpuQuerySetImpl {
+    resourceType = 'query-set';
+    #ownQuerySet;
+    #destroyed = false;
+    #available = true;
+    #readBuffer = undefined;
+    #resolveBuffer = undefined;
+    [$soul];
+    [$internal];
+    constructor(root, type, count, rawQuerySet) {
+        this.#ownQuerySet = !rawQuerySet;
+        this[$soul] = {
+            type: 'query-set',
+            device: root.device,
+            queryType: type,
+            count,
+            raw: rawQuerySet,
+            label: undefined,
+        };
+        // oxlint-disable-next-line typescript/no-this-alias
+        const self = this;
+        this[$internal] = {
+            get readBuffer() {
+                if (!self.#readBuffer) {
+                    self.#readBuffer = self[$soul].device.createBuffer({
+                        size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
+                        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+                    });
+                }
+                return self.#readBuffer;
+            },
+            get resolveBuffer() {
+                if (!self.#resolveBuffer) {
+                    self.#resolveBuffer = self[$soul].device.createBuffer({
+                        size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
+                        usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+                    });
+                }
+                return self.#resolveBuffer;
+            },
+            materialize: () => {
+                if (this.#destroyed) {
+                    throw new Error('This QuerySet has been destroyed.');
+                }
+                const soul = this[$soul];
+                if (!soul.raw) {
+                    soul.raw = soul.device.createQuerySet({
+                        type: soul.queryType,
+                        count: soul.count,
+                    });
+                }
+                return soul.raw;
+            },
+        };
+    }
+    get type() {
+        return this[$soul].queryType;
+    }
+    get count() {
+        return this[$soul].count;
+    }
+    get querySet() {
+        return this[$internal].materialize();
+    }
+    get destroyed() {
+        return this.#destroyed;
+    }
+    get available() {
+        return this.#available;
+    }
+    $name(label) {
+        setName(this, label);
+        const raw = this[$soul].raw;
+        if (raw) {
+            raw.label = label;
+        }
+        return this;
+    }
+    resolve() {
+        if (this.#destroyed) {
+            throw new Error('This QuerySet has been destroyed.');
+        }
+        if (!this.#available) {
+            throw new Error('This QuerySet is busy resolving or reading.');
+        }
+        const commandEncoder = this[$soul].device.createCommandEncoder();
+        commandEncoder.resolveQuerySet(this.querySet, 0, this.count, this[$internal].resolveBuffer, 0);
+        this[$soul].device.queue.submit([commandEncoder.finish()]);
+    }
+    async read() {
+        if (!this.#resolveBuffer) {
+            throw new Error('QuerySet must be resolved before reading.');
+        }
+        this.#available = false;
+        try {
+            const commandEncoder = this[$soul].device.createCommandEncoder();
+            commandEncoder.copyBufferToBuffer(this[$internal].resolveBuffer, 0, this[$internal].readBuffer, 0, this.count * BigUint64Array.BYTES_PER_ELEMENT);
+            this[$soul].device.queue.submit([commandEncoder.finish()]);
+            const readBuffer = this[$internal].readBuffer;
+            await readBuffer.mapAsync(GPUMapMode.READ);
+            const data = new BigUint64Array(readBuffer.getMappedRange().slice());
+            readBuffer.unmap();
+            return Array.from(data);
+        }
+        finally {
+            this.#available = true;
+        }
+    }
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+        this.#destroyed = true;
+        if (this[$soul].raw && this.#ownQuerySet) {
+            this[$soul].raw.destroy();
+        }
+        this.#readBuffer?.destroy();
+        this.#resolveBuffer?.destroy();
+        this.#readBuffer = this.#resolveBuffer = undefined;
+    }
 }
-var TgpuQuerySetImpl = class {
-	resourceType = "query-set";
-	type;
-	count;
-	#rawQuerySet;
-	#device;
-	#querySet;
-	#ownQuerySet;
-	#destroyed = false;
-	#available = true;
-	#readBuffer = void 0;
-	#resolveBuffer = void 0;
-	constructor(root, type, count, rawQuerySet) {
-		this.#device = root.device;
-		this.type = type;
-		this.count = count;
-		this.#rawQuerySet = rawQuerySet;
-		this.#ownQuerySet = !rawQuerySet;
-		this.#querySet = rawQuerySet;
-	}
-	get querySet() {
-		if (this.#destroyed) throw new Error("This QuerySet has been destroyed.");
-		if (this.#rawQuerySet) return this.#rawQuerySet;
-		if (this.#querySet) return this.#querySet;
-		this.#querySet = this.#device.createQuerySet({
-			type: this.type,
-			count: this.count
-		});
-		return this.#querySet;
-	}
-	get destroyed() {
-		return this.#destroyed;
-	}
-	get available() {
-		return this.#available;
-	}
-	get [$internal]() {
-		const self = this;
-		return {
-			get readBuffer() {
-				if (!self.#readBuffer) self.#readBuffer = self.#device.createBuffer({
-					size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
-					usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
-				});
-				return self.#readBuffer;
-			},
-			get resolveBuffer() {
-				if (!self.#resolveBuffer) self.#resolveBuffer = self.#device.createBuffer({
-					size: self.count * BigUint64Array.BYTES_PER_ELEMENT,
-					usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
-				});
-				return self.#resolveBuffer;
-			}
-		};
-	}
-	$name(label) {
-		setName(this, label);
-		if (this.#querySet) this.#querySet.label = label;
-		return this;
-	}
-	resolve() {
-		if (this.#destroyed) throw new Error("This QuerySet has been destroyed.");
-		if (!this.#available) throw new Error("This QuerySet is busy resolving or reading.");
-		const commandEncoder = this.#device.createCommandEncoder();
-		commandEncoder.resolveQuerySet(this.querySet, 0, this.count, this[$internal].resolveBuffer, 0);
-		this.#device.queue.submit([commandEncoder.finish()]);
-	}
-	async read() {
-		if (!this.#resolveBuffer) throw new Error("QuerySet must be resolved before reading.");
-		this.#available = false;
-		try {
-			const commandEncoder = this.#device.createCommandEncoder();
-			commandEncoder.copyBufferToBuffer(this[$internal].resolveBuffer, 0, this[$internal].readBuffer, 0, this.count * BigUint64Array.BYTES_PER_ELEMENT);
-			this.#device.queue.submit([commandEncoder.finish()]);
-			const readBuffer = this[$internal].readBuffer;
-			await readBuffer.mapAsync(GPUMapMode.READ);
-			const data = new BigUint64Array(readBuffer.getMappedRange().slice());
-			readBuffer.unmap();
-			return Array.from(data);
-		} finally {
-			this.#available = true;
-		}
-	}
-	destroy() {
-		if (this.#destroyed) return;
-		this.#destroyed = true;
-		if (this.#querySet && this.#ownQuerySet) this.#querySet.destroy();
-		this.#readBuffer?.destroy();
-		this.#resolveBuffer?.destroy();
-		this.#readBuffer = this.#resolveBuffer = void 0;
-	}
-};
-
-//#endregion
-export { INTERNAL_createQuerySet, isQuerySet };

package/core/rawCodeSnippet/tgpuRawCodeSnippet.d.ts

@@ -1,22 +1,18 @@
-import { $gpuValueOf } from "../../shared/symbols.js";
-import { Origin } from "../../data/snippet.js";
-import { BaseData } from "../../data/wgslTypes.js";
-import { InferGPU } from "../../shared/repr.js";
-import { AnyData } from "../../data/dataTypes.js";
-
-//#region src/core/rawCodeSnippet/tgpuRawCodeSnippet.d.ts
-
+import type { AnyData } from '../../data/dataTypes.ts';
+import { type Origin } from '../../data/snippet.ts';
+import type { BaseData } from '../../data/wgslTypes.ts';
+import type { InferGPU } from '../../shared/repr.ts';
+import { $gpuValueOf } from '../../shared/symbols.ts';
 /**
  * Extra declaration that will be included in final WGSL code
  * when resolving objects that use it.
  */
-interface TgpuRawCodeSnippet<TDataType extends BaseData> {
-  $: InferGPU<TDataType>;
-  value: InferGPU<TDataType>;
-  readonly [$gpuValueOf]: InferGPU<TDataType>;
-  $uses(dependencyMap: Record<string, unknown>): this;
+export interface TgpuRawCodeSnippet<TDataType extends BaseData> {
+    $: InferGPU<TDataType>;
+    readonly [$gpuValueOf]: InferGPU<TDataType>;
+    $uses(dependencyMap: Record<string, unknown>): this;
 }
-type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument' | 'constant-immutable-def' | 'runtime-immutable-def'>;
+export type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument' | 'constant-immutable-def' | 'runtime-immutable-def'>;
 /**
  * An advanced API that creates a typed shader expression which
  * can be injected into the final shader bundle upon use.
@@ -24,6 +20,7 @@ type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument
  * @param expression The code snippet that will be injected in place of `foo.$`
  * @param type The type of the expression
  * @param [origin='runtime'] Where the value originates from.
+ * @param [possibleSideEffects=true] Whether generating this snippet may produce a WGSL expression with observable side-effects (e.g. calling a barrier, discarding a fragment, or writing to memory).
  *
  * **-- Which origin to choose?**
  *
@@ -42,7 +39,7 @@ type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument
  * // final shader bundle, but we cannot
  * // refer to it in any other way.
  * const existingGlobal = tgpu['~unstable']
- *   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant');
+ *   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant', false);
  *
  * const foo = () => {
  *   'use gpu';
@@ -55,6 +52,4 @@ type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'local-def' | 'argument
  * // }
  * ```
  */
-declare function rawCodeSnippet<TDataType extends AnyData>(expression: string, type: TDataType, origin?: RawCodeSnippetOrigin | undefined): TgpuRawCodeSnippet<TDataType>;
-//#endregion
-export { RawCodeSnippetOrigin, TgpuRawCodeSnippet, rawCodeSnippet };
+export declare function rawCodeSnippet<TDataType extends AnyData>(expression: string, type: TDataType, origin?: RawCodeSnippetOrigin | undefined, possibleSideEffects?: boolean | undefined): TgpuRawCodeSnippet<TDataType>;

package/core/rawCodeSnippet/tgpuRawCodeSnippet.js

@@ -1,94 +1,93 @@
-import { $gpuValueOf, $internal, $ownSnippet, $resolve } from "../../shared/symbols.js";
 import { snip } from "../../data/snippet.js";
-import { inCodegenMode } from "../../execMode.js";
-import { valueProxyHandler } from "../valueProxyUtils.js";
+import { makeDereferenceable } from "../../tgsl/makeDereferenceable.js";
+import { makeResolvable } from "../../tgsl/makeResolvable.js";
+import { $gpuValueOf, $internal } from "../../shared/symbols.js";
 import { replaceExternalsInWgsl } from "../resolve/externals.js";
-
-//#region src/core/rawCodeSnippet/tgpuRawCodeSnippet.ts
 /**
-* An advanced API that creates a typed shader expression which
-* can be injected into the final shader bundle upon use.
-*
-* @param expression The code snippet that will be injected in place of `foo.$`
-* @param type The type of the expression
-* @param [origin='runtime'] Where the value originates from.
-*
-* **-- Which origin to choose?**
-*
-* Usually 'runtime' (the default) is a safe bet, but if you're sure that the expression or
-* computation is constant (either a reference to a constant, a numeric literal,
-* or an operation on constants), then pass 'constant' as it might lead to better
-* optimizations.
-*
-* If what the expression is a direct reference to an existing value (e.g. a uniform, a
-* storage binding, ...), then choose from 'uniform', 'mutable', 'readonly', 'workgroup',
-* 'private' or 'handle' depending on the address space of the referred value.
-*
-* @example
-* ```ts
-* // An identifier that we know will be in the
-* // final shader bundle, but we cannot
-* // refer to it in any other way.
-* const existingGlobal = tgpu['~unstable']
-*   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant');
-*
-* const foo = () => {
-*   'use gpu';
-*   return existingGlobal.$ * 2;
-* };
-*
-* const wgsl = tgpu.resolve([foo]);
-* // fn foo() -> f32 {
-* //   return EXISTING_GLOBAL * 2;
-* // }
-* ```
-*/
-function rawCodeSnippet(expression, type, origin = "runtime") {
-	return new TgpuRawCodeSnippetImpl(expression, type, origin);
+ * An advanced API that creates a typed shader expression which
+ * can be injected into the final shader bundle upon use.
+ *
+ * @param expression The code snippet that will be injected in place of `foo.$`
+ * @param type The type of the expression
+ * @param [origin='runtime'] Where the value originates from.
+ * @param [possibleSideEffects=true] Whether generating this snippet may produce a WGSL expression with observable side-effects (e.g. calling a barrier, discarding a fragment, or writing to memory).
+ *
+ * **-- Which origin to choose?**
+ *
+ * Usually 'runtime' (the default) is a safe bet, but if you're sure that the expression or
+ * computation is constant (either a reference to a constant, a numeric literal,
+ * or an operation on constants), then pass 'constant' as it might lead to better
+ * optimizations.
+ *
+ * If what the expression is a direct reference to an existing value (e.g. a uniform, a
+ * storage binding, ...), then choose from 'uniform', 'mutable', 'readonly', 'workgroup',
+ * 'private' or 'handle' depending on the address space of the referred value.
+ *
+ * @example
+ * ```ts
+ * // An identifier that we know will be in the
+ * // final shader bundle, but we cannot
+ * // refer to it in any other way.
+ * const existingGlobal = tgpu['~unstable']
+ *   .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant', false);
+ *
+ * const foo = () => {
+ *   'use gpu';
+ *   return existingGlobal.$ * 2;
+ * };
+ *
+ * const wgsl = tgpu.resolve([foo]);
+ * // fn foo() -> f32 {
+ * //   return EXISTING_GLOBAL * 2;
+ * // }
+ * ```
+ */
+export function rawCodeSnippet(expression, type, origin = 'runtime', possibleSideEffects = true) {
+    return new TgpuRawCodeSnippetImpl(expression, type, origin, possibleSideEffects);
+}
+// --------------
+// Implementation
+// --------------
+class TgpuRawCodeSnippetImpl {
+    dataType;
+    origin;
+    possibleSideEffects;
+    #expression;
+    #externals;
+    static {
+        TgpuRawCodeSnippetImpl.prototype[$internal] = true;
+        makeDereferenceable(makeResolvable(TgpuRawCodeSnippetImpl.prototype, {
+            asString() {
+                return `raw(${String(this.dataType)}): "${this.#expression}"`;
+            },
+            resolve(ctx) {
+                const replacedExpression = replaceExternalsInWgsl(ctx, this.#externals ?? {}, this.#expression);
+                return snip(replacedExpression, this.dataType, this.origin, this.possibleSideEffects);
+            },
+        }), {
+            codegenMode: {
+                getBaseSnippet(trackingProxy) {
+                    return snip(trackingProxy, this.dataType, this.origin, this.possibleSideEffects);
+                },
+            },
+            normalMode: {
+                get() {
+                    throw new Error('Raw code snippets can only be used on the GPU.');
+                },
+            },
+        });
+    }
+    constructor(expression, type, origin, possibleSideEffects) {
+        this.dataType = type;
+        this.origin = origin;
+        this.possibleSideEffects = possibleSideEffects;
+        this.#expression = expression;
+    }
+    $uses(dependencyMap) {
+        if (this.#externals !== undefined) {
+            throw new Error("Cannot call '$uses' multiple times. If you wish to override dependencies, use slots or accessors instead.");
+        }
+        this.#externals = dependencyMap;
+        return this;
+    }
 }
-var TgpuRawCodeSnippetImpl = class {
-	[$internal];
-	dataType;
-	origin;
-	#expression;
-	#externals;
-	constructor(expression, type, origin) {
-		this[$internal] = true;
-		this.dataType = type;
-		this.origin = origin;
-		this.#expression = expression;
-	}
-	$uses(dependencyMap) {
-		if (this.#externals !== void 0) throw new Error("Cannot call '$uses' multiple times. If you wish to override dependencies, use slots or accessors instead.");
-		this.#externals = dependencyMap;
-		return this;
-	}
-	[$resolve](ctx) {
-		return snip(replaceExternalsInWgsl(ctx, this.#externals ?? {}, this.#expression), this.dataType, this.origin);
-	}
-	toString() {
-		return `raw(${String(this.dataType)}): "${this.#expression}"`;
-	}
-	get [$gpuValueOf]() {
-		const dataType = this.dataType;
-		const origin = this.origin;
-		return new Proxy({
-			[$internal]: true,
-			get [$ownSnippet]() {
-				return snip(this, dataType, origin);
-			},
-			[$resolve]: (ctx) => ctx.resolve(this),
-			toString: () => `raw(${String(this.dataType)}): "${this.#expression}".$`
-		}, valueProxyHandler);
-	}
-	get $() {
-		if (!inCodegenMode()) throw new Error("Raw code snippets can only be used on the GPU.");
-		return this[$gpuValueOf];
-	}
-	get value() {
-		return this.$;
-	}
-};
-
-//#endregion
-export { rawCodeSnippet };

package/core/resolve/externals.d.ts

@@ -1,12 +1,29 @@
-import "../../types.js";
-import "../function/fnCore.js";
-
-//#region src/core/resolve/externals.d.ts
-
+import { type ResolutionCtx } from '../../types.ts';
+import type { FnExternals } from '../function/fnCore.ts';
 /**
  * A key-value mapping where keys represent identifiers within shader code,
  * and values can either be another ExternalMap, or be any type that can be resolved to a code string.
  */
-type ExternalMap = Record<string, unknown>;
-//#endregion
-export { ExternalMap };
+export type ExternalMap = Record<string, unknown>;
+/**
+ * Merges function externals into one map.
+ */
+export declare function mergeFunctionExternals(fnExternals: FnExternals): ExternalMap;
+export declare function addArgTypesToExternals(implementation: string, argTypes: unknown[], core: {
+    setExternals: (key: 'args', externals: ExternalMap) => void;
+}): void;
+export declare function addReturnTypeToExternals(implementation: string, returnType: unknown, core: {
+    setExternals: (key: 'out', externals: ExternalMap) => void;
+}): void;
+export declare const anyIdent: RegExp;
+export declare const boundedPropChain: RegExp;
+/**
+ * Replaces all occurrences of external names in WGSL code with their resolved values.
+ * It adds all necessary definitions to the resolution context.
+ * @param ctx - The resolution context.
+ * @param externalMap - The external map. Assumes that keys don't contain dots.
+ * @param wgsl - The WGSL code.
+ *
+ * @returns The WGSL code with all external names replaced with their resolved values.
+ */
+export declare function replaceExternalsInWgsl(ctx: ResolutionCtx, externalMap: ExternalMap, wgsl: string): string;

package/core/resolve/externals.js

@@ -1,65 +1,89 @@
+import { isLooseData } from "../../data/dataTypes.js";
 import { isWgslStruct } from "../../data/wgslTypes.js";
 import { getName, hasTinyestMetadata, isNamable, setName } from "../../shared/meta.js";
-import { isLooseData } from "../../data/dataTypes.js";
+import { logger } from "../../tgpuLogger.js";
 import { isWgsl } from "../../types.js";
-
-//#region src/core/resolve/externals.ts
 function isResolvable(value) {
-	return isWgsl(value) || isLooseData(value) || hasTinyestMetadata(value);
+    return isWgsl(value) || isLooseData(value) || hasTinyestMetadata(value);
 }
 /**
-* Merges function externals into one map.
-*/
-function mergeFunctionExternals(fnExternals) {
-	const base = fnExternals.pluginProvided ?? fnExternals.userProvided ?? {};
-	const result = Object.defineProperties({}, Object.getOwnPropertyDescriptors(base));
-	for (const flatExternal of [fnExternals.args, fnExternals.out].filter((e) => e !== void 0)) for (const [key, value] of Object.entries(flatExternal)) {
-		if (key in result && result[key] !== value) throw new Error(`Key '${key}' appears in externals despite already being used for argument/return type. Please rename this external.`);
-		result[key] = value;
-	}
-	return result;
-}
-function addArgTypesToExternals(implementation, argTypes, core) {
-	const argTypeNames = [...implementation.matchAll(/:\s*(?<arg>.*?)\s*[,)]/g)].map((found) => found?.[1]);
-	const args = Object.fromEntries(argTypes.flatMap((argType, i) => {
-		const argTypeName = argTypeNames?.[i];
-		return isWgslStruct(argType) && argTypeName !== void 0 ? [[argTypeName, argType]] : [];
-	}));
-	core.setExternals("args", args);
+ * Merges function externals into one map.
+ */
+export function mergeFunctionExternals(fnExternals) {
+    const base = fnExternals.pluginProvided ?? fnExternals.userProvided ?? {};
+    // avoid calling any of the getters
+    const result = Object.defineProperties({}, Object.getOwnPropertyDescriptors(base));
+    for (const flatExternal of [fnExternals.args, fnExternals.out].filter((e) => e !== undefined)) {
+        for (const [key, value] of Object.entries(flatExternal)) {
+            if (key in result && result[key] !== value) {
+                throw new Error(`Key '${key}' appears in externals despite already being used for argument/return type. Please rename this external.`);
+            }
+            result[key] = value;
+        }
+    }
+    return result;
 }
-function addReturnTypeToExternals(implementation, returnType, core) {
-	const matched = implementation.match(/->\s(?<output>[\w\d_]+)\s{/);
-	const outputName = matched ? matched[1]?.trim() : void 0;
-	if (isWgslStruct(returnType) && outputName && !/\s/g.test(outputName)) core.setExternals("out", { [outputName]: returnType });
+export function addArgTypesToExternals(implementation, argTypes, core) {
+    const argTypeNames = [...implementation.matchAll(/:\s*(?<arg>.*?)\s*[,)]/g)].map((found) => found?.[1]);
+    const args = Object.fromEntries(argTypes.flatMap((argType, i) => {
+        const argTypeName = argTypeNames?.[i];
+        return isWgslStruct(argType) && argTypeName !== undefined ? [[argTypeName, argType]] : [];
+    }));
+    core.setExternals('args', args);
 }
-function identifierRegex(name) {
-	return new RegExp(`(?<![\\w\\$_.])${name.replaceAll(".", "\\.").replaceAll("$", "\\$")}(?![\\w\\$_])`, "g");
+export function addReturnTypeToExternals(implementation, returnType, core) {
+    const matched = implementation.match(/->\s(?<output>[\w\d_]+)\s{/);
+    const outputName = matched ? matched[1]?.trim() : undefined;
+    if (isWgslStruct(returnType) && outputName && !/\s/g.test(outputName)) {
+        core.setExternals('out', { [outputName]: returnType });
+    }
 }
+export const anyIdent = /([$_\p{XID_Start}][$\p{XID_Continue}]*)/u; // WGSL ident, modified to include $
+const anyPropChain = new RegExp(`(${anyIdent.source})(\\.${anyIdent.source})*`, 'ug');
+export const boundedPropChain = new RegExp(`(?<![\\p{XID_Continue}\\$.])${anyPropChain.source}(?![\\p{XID_Continue}\\$])`, 'ug');
 /**
-* Replaces all occurrences of external names in WGSL code with their resolved values.
-* It adds all necessary definitions to the resolution context.
-* @param ctx - The resolution context.
-* @param externalMap - The external map.
-* @param wgsl - The WGSL code.
-*
-* @returns The WGSL code with all external names replaced with their resolved values.
-*/
-function replaceExternalsInWgsl(ctx, externalMap, wgsl) {
-	return Object.entries(externalMap).reduce((acc, [externalName, external]) => {
-		const externalRegex = identifierRegex(externalName);
-		if (wgsl && externalName !== "Out" && externalName !== "in" && !externalRegex.test(wgsl)) console.warn(`The external '${externalName}' wasn't used in the resolved template.`);
-		if (isResolvable(external)) {
-			if (isNamable(external) && getName(external) === void 0) setName(external, externalName.split(".").at(-1));
-			return acc.replaceAll(externalRegex, ctx.resolve(external).value);
-		}
-		if (external !== null && typeof external === "object") {
-			const foundProperties = [...wgsl.matchAll(new RegExp(`${externalName.replaceAll(".", "\\.").replaceAll("$", "\\$")}\\.(?<prop>.*?)(?![\\w\\$_])`, "g"))].map((found) => found[1]);
-			return [...new Set(foundProperties)].reduce((innerAcc, prop) => prop && prop in external ? replaceExternalsInWgsl(ctx, { [`${externalName}.${prop}`]: external[prop] }, innerAcc) : innerAcc, acc);
-		}
-		console.warn(`During resolution, the external '${externalName}' has been omitted. Only TGPU resources, 'use gpu' functions, primitives, and plain JS objects can be used as externals.`);
-		return acc;
-	}, wgsl);
+ * Replaces all occurrences of external names in WGSL code with their resolved values.
+ * It adds all necessary definitions to the resolution context.
+ * @param ctx - The resolution context.
+ * @param externalMap - The external map. Assumes that keys don't contain dots.
+ * @param wgsl - The WGSL code.
+ *
+ * @returns The WGSL code with all external names replaced with their resolved values.
+ */
+export function replaceExternalsInWgsl(ctx, externalMap, wgsl) {
+    const keys = Object.keys(externalMap);
+    if (keys.length === 0) {
+        return wgsl;
+    }
+    const maybeInvalidKey = keys.find((key) => key.includes('.'));
+    if (maybeInvalidKey) {
+        throw new Error(`External key '${maybeInvalidKey}' contains invalid character '.'`);
+    }
+    return wgsl.replaceAll(boundedPropChain, (match) => {
+        const chain = match.split('.');
+        if (!Object.hasOwn(externalMap, chain.at(0))) {
+            // this prop access does not start with an external
+            return match;
+        }
+        let currentItem = externalMap;
+        let suffix = '';
+        for (const [i, elem] of chain.entries()) {
+            currentItem = currentItem[elem];
+            if (isResolvable(currentItem) || typeof currentItem === 'string') {
+                suffix = chain
+                    .slice(i + 1)
+                    .map((s) => `.${s}`)
+                    .join('');
+                if (isNamable(currentItem) && getName(currentItem) === undefined) {
+                    setName(currentItem, chain.slice(0, i + 1).join('_'));
+                }
+                break;
+            }
+            if (typeof currentItem !== 'object' || currentItem === null || i === chain.length - 1) {
+                logger.warn('external-omitted', `During resolution, the external '${chain.slice(0, i + 1).join('.')}' has been omitted. Only TGPU resources, 'use gpu' functions, primitives, and plain JS objects can be used as externals.`);
+                return match;
+            }
+        }
+        return ctx.resolve(currentItem).value + suffix;
+    });
 }
-
-//#endregion
-export { addArgTypesToExternals, addReturnTypeToExternals, mergeFunctionExternals, replaceExternalsInWgsl };