@galacean/engine-shader-compiler 2.0.0-alpha.51 → 2.0.0-alpha.53

package/bundler/rollup.cjs.js

@@ -5,7 +5,6 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var fs = require('node:fs');
 var path = require('node:path');
 var node_module = require('node:module');
-var node_url = require('node:url');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -30,7 +29,11 @@ function _interopNamespace(e) {
 var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
 var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
 
-/** Normalize to forward slashes (Windows uses `\`; downstream regex/keys assume `/`). */ function normalizePath(p) {
+/**
+ * Converts a filesystem path to the slash-separated form used by shader asset keys.
+ * @param p - Filesystem path.
+ * @returns Slash-separated path.
+ */ function normalizePath(p) {
     return p.split(path__default["default"].sep).join("/");
 }
 /** Recursively find all files with a given extension. */ function findFiles(dir, ext) {
@@ -67,7 +70,12 @@ var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
         dir = path__default["default"].dirname(dir);
     }
 }
-async function runFull(options) {
+/**
+ * Precompiles the current shader source tree once.
+ * @param options - Source, output, cleanup, and artifact-generation options.
+ * @returns An object containing the number of shader sources that failed to compile.
+ * @throws Error when the input tree or an explicitly selected source is invalid.
+ */ async function runFull(options) {
     const inputDir = path__default["default"].resolve(options.input);
     const outputDir = path__default["default"].resolve(options.output);
     const platformTarget = options.platformTarget ?? 0;
@@ -82,22 +90,13 @@ async function runFull(options) {
         emitSources(inputDir);
     }
     const shaderCompiler = await loadShaderCompiler();
-    shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
+    shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
     let failed = 0;
     if (options.only) {
         const target = path__default["default"].resolve(options.only);
         if (!compileSingle(shaderCompiler, target, inputDir, outputDir, platformTarget)) failed++;
     } else {
-        const shaderFiles = findFiles(inputDir, ".shader");
-        console.log(`[shader-compiler-bundler] Precompiling ${shaderFiles.length} shader(s)...`);
-        for (const file of shaderFiles){
-            if (!compileSingle(shaderCompiler, file, inputDir, outputDir, platformTarget)) failed++;
-        }
-        if (options.clean) {
-            const removed = cleanOrphanedBundles(shaderFiles, inputDir, outputDir);
-            if (removed > 0) console.log(`[shader-compiler-bundler] Cleaned ${removed} orphaned .shaderc file(s).`);
-        }
-        if (failed > 0) console.warn(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
+        failed = compileAll(shaderCompiler, inputDir, outputDir, platformTarget, options.clean);
     }
     if (options.emitIndex) {
         emitIndex(outputDir);
@@ -106,12 +105,23 @@ async function runFull(options) {
         failed
     };
 }
-async function startWatcher(options) {
+/**
+ * Watches one shader source tree and serializes incremental rebuilds.
+ * @param options - Source, output, cleanup, and artifact-generation options.
+ * @returns Once the filesystem watcher has been installed.
+ * @throws Error when the initial include registry cannot be loaded.
+ */ async function startWatcher(options) {
     const inputDir = path__default["default"].resolve(options.input);
     const outputDir = path__default["default"].resolve(options.output);
     const platformTarget = options.platformTarget ?? 0;
+    if (!fs__default["default"].existsSync(inputDir)) {
+        throw new Error(`Input directory does not exist: ${inputDir}`);
+    }
+    fs__default["default"].mkdirSync(outputDir, {
+        recursive: true
+    });
     const shaderCompiler = await loadShaderCompiler();
-    shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
+    shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
     // .glsl change → full recompile (can't cheaply track include graphs).
     // .shader change → single-file recompile.
     const handleInputChange = async (filename)=>{
@@ -120,8 +130,11 @@ async function startWatcher(options) {
         const fullPath = path__default["default"].join(inputDir, filename);
         if (norm.endsWith(".glsl")) {
             console.log(`[shader-compiler-bundler] Include changed (${norm}), full recompile...`);
-            shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
-            runFull(options).catch((e)=>console.error(e));
+            if (options.emitSources) emitSources(inputDir);
+            shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
+            const failed = compileAll(shaderCompiler, inputDir, outputDir, platformTarget, options.clean);
+            if (options.emitIndex) emitIndex(outputDir);
+            if (failed > 0) console.error(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
             return;
         }
         if (!norm.endsWith(".shader")) return;
@@ -134,68 +147,92 @@ async function startWatcher(options) {
         if (options.emitIndex) emitIndex(outputDir);
     };
     console.log(`[shader-compiler-bundler] Watching ${inputDir} ...`);
+    let changeQueue = Promise.resolve();
     fs__default["default"].watch(inputDir, {
         recursive: true
     }, (_event, filename)=>{
-        handleInputChange(filename).catch((e)=>console.error(e));
+        changeQueue = changeQueue.then(()=>handleInputChange(filename)).catch((e)=>console.error(e));
     });
 }
+function compileAll(shaderCompiler, inputDir, outputDir, platformTarget, clean) {
+    const shaderFiles = findFiles(inputDir, ".shader");
+    console.log(`[shader-compiler-bundler] Precompiling ${shaderFiles.length} shader(s)...`);
+    let failed = 0;
+    for (const file of shaderFiles){
+        if (!compileSingle(shaderCompiler, file, inputDir, outputDir, platformTarget)) failed++;
+    }
+    if (clean) {
+        const removed = cleanOrphanedBundles(shaderFiles, inputDir, outputDir);
+        if (removed > 0) console.log(`[shader-compiler-bundler] Cleaned ${removed} orphaned .shaderc file(s).`);
+    }
+    if (failed > 0) console.warn(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
+    return failed;
+}
 async function loadShaderCompiler() {
-    // @ts-ignore — `../dist/main.js` is the compiled runtime entry; no .ts source.
-    // Bundler ships at `<pkg>/bundler/` and the runtime at `<pkg>/dist/`, so this
-    // resolves to the sibling `dist/` from `bundler/cli.js` at runtime.
-    const mod = await Promise.resolve().then(function () { return /*#__PURE__*/_interopNamespace(require('../dist/main.js')); });
-    const instance = new mod.ShaderCompiler();
-    if (typeof instance._precompile !== "function") {
-        throw new Error("ShaderCompiler._precompile is not available; rebuild @galacean/engine-shader-compiler first.");
+    const mod = await (process.env.GALACEAN_SHADER_COMPILER_BOOTSTRAP === "true" ? importBootstrapPrecompiler() : importReleasePrecompiler());
+    const instance = new mod.ShaderPrecompiler();
+    if (typeof instance.precompile !== "function") {
+        throw new Error("ShaderPrecompiler is unavailable; rebuild @galacean/engine-shader-compiler first.");
     }
     return instance;
 }
+async function importBootstrapPrecompiler() {
+    // @ts-expect-error generated repo-local runtime has no declaration file
+    return Promise.resolve().then(function () { return /*#__PURE__*/_interopNamespace(require('../.bootstrap/main.js')); });
+}
+async function importReleasePrecompiler() {
+    // @ts-expect-error generated Node-only runtime has no declaration file
+    return Promise.resolve().then(function () { return /*#__PURE__*/_interopNamespace(require('../dist/precompile.main.js')); });
+}
 // Local .glsl come from inputDir; standard library comes from
 // `@galacean/engine-shader/sources` with a sibling-dir fallback for engine self-build cold-start.
 async function collectIncludeMap(inputDir) {
-    const map = {};
+    const map = Object.create(null);
     for (const file of findFiles(inputDir, ".glsl")){
         const relPath = normalizePath(path__default["default"].relative(inputDir, file));
-        map[relPath] = fs__default["default"].readFileSync(file, "utf-8");
+        addIncludeSource(map, relPath, fs__default["default"].readFileSync(file, "utf-8"));
     }
-    let usedRelease = false;
     // Resolve from inputDir's node_modules so consumers without transitive linkage to shader-compiler can still find it.
+    const requireFromInput = node_module.createRequire(path__default["default"].join(inputDir, "package.json"));
+    let sourcesPath;
     try {
-        const requireFromInput = node_module.createRequire(path__default["default"].join(inputDir, "package.json"));
-        const sourcesPath = requireFromInput.resolve("@galacean/engine-shader/sources");
-        const { shaderLibrary } = await (function (t) { return Promise.resolve().then(function () { return /*#__PURE__*/_interopNamespace(require(t)); }); })(node_url.pathToFileURL(sourcesPath).href);
+        sourcesPath = requireFromInput.resolve("@galacean/engine-shader/sources");
+    } catch (error) {
+        if (error.code !== "MODULE_NOT_FOUND") throw error;
+    }
+    if (sourcesPath) {
+        const { shaderLibrary } = requireFromInput(sourcesPath);
         for (const { source, path: chunkPath } of shaderLibrary){
-            map[chunkPath] = source;
+            addIncludeSource(map, chunkPath, source);
         }
-        usedRelease = true;
-    } catch  {
-    // engine self-build cold-start: dist/sources.* not yet built; use sibling source.
-    }
-    if (!usedRelease) {
+    } else {
+        // Engine self-build cold-start has no generated sources entry yet.
         const siblingLibrary = path__default["default"].join(path__default["default"].dirname(inputDir), "ShaderLibrary");
         if (fs__default["default"].existsSync(siblingLibrary)) {
             for (const file of findFiles(siblingLibrary, ".glsl")){
                 const rel = normalizePath(path__default["default"].relative(siblingLibrary, file));
-                map[`ShaderLibrary/${rel}`] = fs__default["default"].readFileSync(file, "utf-8");
+                addIncludeSource(map, `ShaderLibrary/${rel}`, fs__default["default"].readFileSync(file, "utf-8"));
             }
         }
     }
     return map;
 }
-// Mirrors `ShaderPass._shaderRootPath` in engine; inlined to keep bundler engine-free.
-const SHADER_ROOT_PATH = "shaders://root/";
+function addIncludeSource(map, key, source) {
+    if (Object.prototype.hasOwnProperty.call(map, key)) {
+        throw new Error(`Shader include "${key}" is registered more than once.`);
+    }
+    map[key] = source;
+}
 function compileSingle(shaderCompiler, shaderPath, inputDir, outputDir, platformTarget) {
+    const relativePath = shaderSourceRelativePath(shaderPath, inputDir);
     const source = fs__default["default"].readFileSync(shaderPath, "utf-8");
-    const relativePath = normalizePath(path__default["default"].relative(inputDir, shaderPath));
     const bundleRelative = relativePath.replace(/\.shader$/, ".shaderc");
     const bundlePath = path__default["default"].join(outputDir, bundleRelative);
-    const basePathForIncludeKey = new URL(relativePath, SHADER_ROOT_PATH).href;
     fs__default["default"].mkdirSync(path__default["default"].dirname(bundlePath), {
         recursive: true
     });
     try {
-        const precompiled = shaderCompiler._precompile(source, platformTarget, basePathForIncludeKey);
+        const precompiled = shaderCompiler.precompile(source, platformTarget, relativePath);
         fs__default["default"].writeFileSync(bundlePath, JSON.stringify(precompiled));
         console.log(`  ${relativePath} -> ${bundleRelative}`);
         return true;
@@ -205,6 +242,13 @@ function compileSingle(shaderCompiler, shaderPath, inputDir, outputDir, platform
         return false;
     }
 }
+function shaderSourceRelativePath(shaderPath, inputDir) {
+    const relativePath = path__default["default"].relative(inputDir, shaderPath);
+    if (relativePath === ".." || relativePath.startsWith(`..${path__default["default"].sep}`) || path__default["default"].isAbsolute(relativePath) || path__default["default"].extname(relativePath) !== ".shader") {
+        throw new Error(`Shader source must be a .shader file inside the input directory: ${shaderPath}`);
+    }
+    return normalizePath(relativePath);
+}
 function cleanOrphanedBundles(shaderFiles, inputDir, outputDir) {
     const aliveSet = new Set(shaderFiles.map((f)=>normalizePath(path__default["default"].relative(inputDir, f)).replace(/\.shader$/, "")));
     const bundleFiles = findFiles(outputDir, ".shaderc");
@@ -229,6 +273,10 @@ function emitIndex(outputDir) {
             importPath: `./${rel}`
         };
     }).sort((a, b)=>a.varName.localeCompare(b.varName));
+    assertUniqueIdentifiers(entries.map(({ varName, importPath })=>({
+            identifier: varName,
+            path: importPath
+        })));
     const imports = entries.map((e)=>`import ${e.varName}Data from "${e.importPath}";`).join("\n");
     const exports = entries.map((e)=>`export const ${e.varName}: IPrecompiledShader = ${e.varName}Data;`).join("\n");
     const content = `// Auto-generated by shader-compiler-precompile --emit-index — do not edit.\nimport type { IPrecompiledShader } from "@galacean/engine-design";\n${imports}\n\n${exports}\n`;
@@ -255,6 +303,10 @@ function emitShaderSourceIndex(rootDir) {
     const importPaths = files.map((f)=>normalizePath(path__default["default"].relative(rootDir, f)));
     const paths = files.map((f)=>normalizePath(path__default["default"].relative(srcDir, f)));
     const ids = importPaths.map((p)=>pathToIdentifier(p, ".shader"));
+    assertUniqueIdentifiers(ids.map((identifier, index)=>({
+            identifier,
+            path: importPaths[index]
+        })));
     const lines = [];
     lines.push("// Auto-generated by shader-compiler-precompile --emit-sources — do not edit.");
     lines.push("");
@@ -280,6 +332,10 @@ function emitLibrarySourceIndex(rootDir) {
     const importPaths = files.map((f)=>normalizePath(path__default["default"].relative(rootDir, f)));
     const paths = files.map((f)=>normalizePath(path__default["default"].relative(srcDir, f)));
     const ids = importPaths.map((p)=>pathToIdentifier(p, ".glsl"));
+    assertUniqueIdentifiers(ids.map((identifier, index)=>({
+            identifier,
+            path: importPaths[index]
+        })));
     const lines = [];
     lines.push("// Auto-generated by shader-compiler-precompile --emit-sources — do not edit.");
     lines.push("");
@@ -295,6 +351,16 @@ function emitLibrarySourceIndex(rootDir) {
     fs__default["default"].writeFileSync(out, lines.join("\n"), "utf-8");
     console.log(`  Emitted library index ${path__default["default"].relative(process.cwd(), out)} (${files.length})`);
 }
+function assertUniqueIdentifiers(entries) {
+    const pathsByIdentifier = new Map();
+    for (const { identifier, path: sourcePath } of entries){
+        const existingPath = pathsByIdentifier.get(identifier);
+        if (existingPath !== undefined) {
+            throw new Error(`Shader asset paths "${existingPath}" and "${sourcePath}" both emit identifier "${identifier}".`);
+        }
+        pathsByIdentifier.set(identifier, sourcePath);
+    }
+}
 function removeBundleFor(shaderPath, inputDir, outputDir) {
     const rel = normalizePath(path__default["default"].relative(inputDir, shaderPath)).replace(/\.shader$/, ".shaderc");
     const bundlePath = path__default["default"].join(outputDir, rel);
@@ -333,6 +399,9 @@ function removeBundleFor(shaderPath, inputDir, outputDir) {
  * - When `precompile` option is set: runs a full precompile in buildStart and,
  *   in watch mode, starts a background watcher that mirrors `.shader` source
  *   changes into `.shaderc` outputs and refreshes the aggregated index.
+ * @param options - Transform filter and optional offline precompile configuration.
+ * @returns Rollup plugin for shader source and artifact modules.
+ * @throws Error during `buildStart` when offline precompilation reports failures.
  */ function shaderCompiler(options = {}) {
     const { filter, precompile } = options;
     const precompileOptions = precompile && {
@@ -347,7 +416,8 @@ function removeBundleFor(shaderPath, inputDir, outputDir) {
         async buildStart () {
             if (!precompileOptions || initialDone) return;
             initialDone = true;
-            await runFull(precompileOptions);
+            const { failed } = await runFull(precompileOptions);
+            if (failed > 0) this.error(`${failed} shader(s) failed to precompile.`);
             if (this.meta.watchMode && !watcherStarted) {
                 watcherStarted = true;
                 startWatcher(precompileOptions).catch((e)=>this.warn(`[shader-compiler] watcher failed: ${e.message}`));

package/bundler/rollup.js

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
 
-/** Normalize to forward slashes (Windows uses `\`; downstream regex/keys assume `/`). */ function normalizePath(p) {
+/**
+ * Converts a filesystem path to the slash-separated form used by shader asset keys.
+ * @param p - Filesystem path.
+ * @returns Slash-separated path.
+ */ function normalizePath(p) {
     return p.split(path.sep).join("/");
 }
 /** Recursively find all files with a given extension. */ function findFiles(dir, ext) {
@@ -40,7 +43,12 @@ import { pathToFileURL } from 'node:url';
         dir = path.dirname(dir);
     }
 }
-async function runFull(options) {
+/**
+ * Precompiles the current shader source tree once.
+ * @param options - Source, output, cleanup, and artifact-generation options.
+ * @returns An object containing the number of shader sources that failed to compile.
+ * @throws Error when the input tree or an explicitly selected source is invalid.
+ */ async function runFull(options) {
     const inputDir = path.resolve(options.input);
     const outputDir = path.resolve(options.output);
     const platformTarget = options.platformTarget ?? 0;
@@ -55,22 +63,13 @@ async function runFull(options) {
         emitSources(inputDir);
     }
     const shaderCompiler = await loadShaderCompiler();
-    shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
+    shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
     let failed = 0;
     if (options.only) {
         const target = path.resolve(options.only);
         if (!compileSingle(shaderCompiler, target, inputDir, outputDir, platformTarget)) failed++;
     } else {
-        const shaderFiles = findFiles(inputDir, ".shader");
-        console.log(`[shader-compiler-bundler] Precompiling ${shaderFiles.length} shader(s)...`);
-        for (const file of shaderFiles){
-            if (!compileSingle(shaderCompiler, file, inputDir, outputDir, platformTarget)) failed++;
-        }
-        if (options.clean) {
-            const removed = cleanOrphanedBundles(shaderFiles, inputDir, outputDir);
-            if (removed > 0) console.log(`[shader-compiler-bundler] Cleaned ${removed} orphaned .shaderc file(s).`);
-        }
-        if (failed > 0) console.warn(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
+        failed = compileAll(shaderCompiler, inputDir, outputDir, platformTarget, options.clean);
     }
     if (options.emitIndex) {
         emitIndex(outputDir);
@@ -79,12 +78,23 @@ async function runFull(options) {
         failed
     };
 }
-async function startWatcher(options) {
+/**
+ * Watches one shader source tree and serializes incremental rebuilds.
+ * @param options - Source, output, cleanup, and artifact-generation options.
+ * @returns Once the filesystem watcher has been installed.
+ * @throws Error when the initial include registry cannot be loaded.
+ */ async function startWatcher(options) {
     const inputDir = path.resolve(options.input);
     const outputDir = path.resolve(options.output);
     const platformTarget = options.platformTarget ?? 0;
+    if (!fs.existsSync(inputDir)) {
+        throw new Error(`Input directory does not exist: ${inputDir}`);
+    }
+    fs.mkdirSync(outputDir, {
+        recursive: true
+    });
     const shaderCompiler = await loadShaderCompiler();
-    shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
+    shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
     // .glsl change → full recompile (can't cheaply track include graphs).
     // .shader change → single-file recompile.
     const handleInputChange = async (filename)=>{
@@ -93,8 +103,11 @@ async function startWatcher(options) {
         const fullPath = path.join(inputDir, filename);
         if (norm.endsWith(".glsl")) {
             console.log(`[shader-compiler-bundler] Include changed (${norm}), full recompile...`);
-            shaderCompiler._setIncludeMap(await collectIncludeMap(inputDir));
-            runFull(options).catch((e)=>console.error(e));
+            if (options.emitSources) emitSources(inputDir);
+            shaderCompiler.setIncludeMap(await collectIncludeMap(inputDir));
+            const failed = compileAll(shaderCompiler, inputDir, outputDir, platformTarget, options.clean);
+            if (options.emitIndex) emitIndex(outputDir);
+            if (failed > 0) console.error(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
             return;
         }
         if (!norm.endsWith(".shader")) return;
@@ -107,68 +120,92 @@ async function startWatcher(options) {
         if (options.emitIndex) emitIndex(outputDir);
     };
     console.log(`[shader-compiler-bundler] Watching ${inputDir} ...`);
+    let changeQueue = Promise.resolve();
     fs.watch(inputDir, {
         recursive: true
     }, (_event, filename)=>{
-        handleInputChange(filename).catch((e)=>console.error(e));
+        changeQueue = changeQueue.then(()=>handleInputChange(filename)).catch((e)=>console.error(e));
     });
 }
+function compileAll(shaderCompiler, inputDir, outputDir, platformTarget, clean) {
+    const shaderFiles = findFiles(inputDir, ".shader");
+    console.log(`[shader-compiler-bundler] Precompiling ${shaderFiles.length} shader(s)...`);
+    let failed = 0;
+    for (const file of shaderFiles){
+        if (!compileSingle(shaderCompiler, file, inputDir, outputDir, platformTarget)) failed++;
+    }
+    if (clean) {
+        const removed = cleanOrphanedBundles(shaderFiles, inputDir, outputDir);
+        if (removed > 0) console.log(`[shader-compiler-bundler] Cleaned ${removed} orphaned .shaderc file(s).`);
+    }
+    if (failed > 0) console.warn(`[shader-compiler-bundler] ${failed} shader(s) failed to precompile.`);
+    return failed;
+}
 async function loadShaderCompiler() {
-    // @ts-ignore — `../dist/main.js` is the compiled runtime entry; no .ts source.
-    // Bundler ships at `<pkg>/bundler/` and the runtime at `<pkg>/dist/`, so this
-    // resolves to the sibling `dist/` from `bundler/cli.js` at runtime.
-    const mod = await import('../dist/main.js');
-    const instance = new mod.ShaderCompiler();
-    if (typeof instance._precompile !== "function") {
-        throw new Error("ShaderCompiler._precompile is not available; rebuild @galacean/engine-shader-compiler first.");
+    const mod = await (process.env.GALACEAN_SHADER_COMPILER_BOOTSTRAP === "true" ? importBootstrapPrecompiler() : importReleasePrecompiler());
+    const instance = new mod.ShaderPrecompiler();
+    if (typeof instance.precompile !== "function") {
+        throw new Error("ShaderPrecompiler is unavailable; rebuild @galacean/engine-shader-compiler first.");
     }
     return instance;
 }
+async function importBootstrapPrecompiler() {
+    // @ts-expect-error generated repo-local runtime has no declaration file
+    return import('../.bootstrap/main.js');
+}
+async function importReleasePrecompiler() {
+    // @ts-expect-error generated Node-only runtime has no declaration file
+    return import('../dist/precompile.main.js');
+}
 // Local .glsl come from inputDir; standard library comes from
 // `@galacean/engine-shader/sources` with a sibling-dir fallback for engine self-build cold-start.
 async function collectIncludeMap(inputDir) {
-    const map = {};
+    const map = Object.create(null);
     for (const file of findFiles(inputDir, ".glsl")){
         const relPath = normalizePath(path.relative(inputDir, file));
-        map[relPath] = fs.readFileSync(file, "utf-8");
+        addIncludeSource(map, relPath, fs.readFileSync(file, "utf-8"));
     }
-    let usedRelease = false;
     // Resolve from inputDir's node_modules so consumers without transitive linkage to shader-compiler can still find it.
+    const requireFromInput = createRequire(path.join(inputDir, "package.json"));
+    let sourcesPath;
     try {
-        const requireFromInput = createRequire(path.join(inputDir, "package.json"));
-        const sourcesPath = requireFromInput.resolve("@galacean/engine-shader/sources");
-        const { shaderLibrary } = await import(pathToFileURL(sourcesPath).href);
+        sourcesPath = requireFromInput.resolve("@galacean/engine-shader/sources");
+    } catch (error) {
+        if (error.code !== "MODULE_NOT_FOUND") throw error;
+    }
+    if (sourcesPath) {
+        const { shaderLibrary } = requireFromInput(sourcesPath);
         for (const { source, path: chunkPath } of shaderLibrary){
-            map[chunkPath] = source;
+            addIncludeSource(map, chunkPath, source);
         }
-        usedRelease = true;
-    } catch  {
-    // engine self-build cold-start: dist/sources.* not yet built; use sibling source.
-    }
-    if (!usedRelease) {
+    } else {
+        // Engine self-build cold-start has no generated sources entry yet.
         const siblingLibrary = path.join(path.dirname(inputDir), "ShaderLibrary");
         if (fs.existsSync(siblingLibrary)) {
             for (const file of findFiles(siblingLibrary, ".glsl")){
                 const rel = normalizePath(path.relative(siblingLibrary, file));
-                map[`ShaderLibrary/${rel}`] = fs.readFileSync(file, "utf-8");
+                addIncludeSource(map, `ShaderLibrary/${rel}`, fs.readFileSync(file, "utf-8"));
             }
         }
     }
     return map;
 }
-// Mirrors `ShaderPass._shaderRootPath` in engine; inlined to keep bundler engine-free.
-const SHADER_ROOT_PATH = "shaders://root/";
+function addIncludeSource(map, key, source) {
+    if (Object.prototype.hasOwnProperty.call(map, key)) {
+        throw new Error(`Shader include "${key}" is registered more than once.`);
+    }
+    map[key] = source;
+}
 function compileSingle(shaderCompiler, shaderPath, inputDir, outputDir, platformTarget) {
+    const relativePath = shaderSourceRelativePath(shaderPath, inputDir);
     const source = fs.readFileSync(shaderPath, "utf-8");
-    const relativePath = normalizePath(path.relative(inputDir, shaderPath));
     const bundleRelative = relativePath.replace(/\.shader$/, ".shaderc");
     const bundlePath = path.join(outputDir, bundleRelative);
-    const basePathForIncludeKey = new URL(relativePath, SHADER_ROOT_PATH).href;
     fs.mkdirSync(path.dirname(bundlePath), {
         recursive: true
     });
     try {
-        const precompiled = shaderCompiler._precompile(source, platformTarget, basePathForIncludeKey);
+        const precompiled = shaderCompiler.precompile(source, platformTarget, relativePath);
         fs.writeFileSync(bundlePath, JSON.stringify(precompiled));
         console.log(`  ${relativePath} -> ${bundleRelative}`);
         return true;
@@ -178,6 +215,13 @@ function compileSingle(shaderCompiler, shaderPath, inputDir, outputDir, platform
         return false;
     }
 }
+function shaderSourceRelativePath(shaderPath, inputDir) {
+    const relativePath = path.relative(inputDir, shaderPath);
+    if (relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath) || path.extname(relativePath) !== ".shader") {
+        throw new Error(`Shader source must be a .shader file inside the input directory: ${shaderPath}`);
+    }
+    return normalizePath(relativePath);
+}
 function cleanOrphanedBundles(shaderFiles, inputDir, outputDir) {
     const aliveSet = new Set(shaderFiles.map((f)=>normalizePath(path.relative(inputDir, f)).replace(/\.shader$/, "")));
     const bundleFiles = findFiles(outputDir, ".shaderc");
@@ -202,6 +246,10 @@ function emitIndex(outputDir) {
             importPath: `./${rel}`
         };
     }).sort((a, b)=>a.varName.localeCompare(b.varName));
+    assertUniqueIdentifiers(entries.map(({ varName, importPath })=>({
+            identifier: varName,
+            path: importPath
+        })));
     const imports = entries.map((e)=>`import ${e.varName}Data from "${e.importPath}";`).join("\n");
     const exports = entries.map((e)=>`export const ${e.varName}: IPrecompiledShader = ${e.varName}Data;`).join("\n");
     const content = `// Auto-generated by shader-compiler-precompile --emit-index — do not edit.\nimport type { IPrecompiledShader } from "@galacean/engine-design";\n${imports}\n\n${exports}\n`;
@@ -228,6 +276,10 @@ function emitShaderSourceIndex(rootDir) {
     const importPaths = files.map((f)=>normalizePath(path.relative(rootDir, f)));
     const paths = files.map((f)=>normalizePath(path.relative(srcDir, f)));
     const ids = importPaths.map((p)=>pathToIdentifier(p, ".shader"));
+    assertUniqueIdentifiers(ids.map((identifier, index)=>({
+            identifier,
+            path: importPaths[index]
+        })));
     const lines = [];
     lines.push("// Auto-generated by shader-compiler-precompile --emit-sources — do not edit.");
     lines.push("");
@@ -253,6 +305,10 @@ function emitLibrarySourceIndex(rootDir) {
     const importPaths = files.map((f)=>normalizePath(path.relative(rootDir, f)));
     const paths = files.map((f)=>normalizePath(path.relative(srcDir, f)));
     const ids = importPaths.map((p)=>pathToIdentifier(p, ".glsl"));
+    assertUniqueIdentifiers(ids.map((identifier, index)=>({
+            identifier,
+            path: importPaths[index]
+        })));
     const lines = [];
     lines.push("// Auto-generated by shader-compiler-precompile --emit-sources — do not edit.");
     lines.push("");
@@ -268,6 +324,16 @@ function emitLibrarySourceIndex(rootDir) {
     fs.writeFileSync(out, lines.join("\n"), "utf-8");
     console.log(`  Emitted library index ${path.relative(process.cwd(), out)} (${files.length})`);
 }
+function assertUniqueIdentifiers(entries) {
+    const pathsByIdentifier = new Map();
+    for (const { identifier, path: sourcePath } of entries){
+        const existingPath = pathsByIdentifier.get(identifier);
+        if (existingPath !== undefined) {
+            throw new Error(`Shader asset paths "${existingPath}" and "${sourcePath}" both emit identifier "${identifier}".`);
+        }
+        pathsByIdentifier.set(identifier, sourcePath);
+    }
+}
 function removeBundleFor(shaderPath, inputDir, outputDir) {
     const rel = normalizePath(path.relative(inputDir, shaderPath)).replace(/\.shader$/, ".shaderc");
     const bundlePath = path.join(outputDir, rel);
@@ -306,6 +372,9 @@ function removeBundleFor(shaderPath, inputDir, outputDir) {
  * - When `precompile` option is set: runs a full precompile in buildStart and,
  *   in watch mode, starts a background watcher that mirrors `.shader` source
  *   changes into `.shaderc` outputs and refreshes the aggregated index.
+ * @param options - Transform filter and optional offline precompile configuration.
+ * @returns Rollup plugin for shader source and artifact modules.
+ * @throws Error during `buildStart` when offline precompilation reports failures.
  */ function shaderCompiler(options = {}) {
     const { filter, precompile } = options;
     const precompileOptions = precompile && {
@@ -320,7 +389,8 @@ function removeBundleFor(shaderPath, inputDir, outputDir) {
         async buildStart () {
             if (!precompileOptions || initialDone) return;
             initialDone = true;
-            await runFull(precompileOptions);
+            const { failed } = await runFull(precompileOptions);
+            if (failed > 0) this.error(`${failed} shader(s) failed to precompile.`);
             if (this.meta.watchMode && !watcherStarted) {
                 watcherStarted = true;
                 startWatcher(precompileOptions).catch((e)=>this.warn(`[shader-compiler] watcher failed: ${e.message}`));