nagami-rs 2026.7.2 → 2026.9.1

package/README.md

@@ -36,6 +36,7 @@ Nagami lowers WGSL into [Naga IR](https://github.com/gfx-rs/wgpu/tree/trunk/naga
 - Float precision trimming - cap decimal places or significant figures, per type (lossy, opt-in)
 - Preamble support - external declarations excluded from output
 - Library modules - shader fragments without entry points preserved
+- Name map - original -> final identifier mapping for hosts that address shaders by source names
 
 Runs passes in fixed-point sweeps until the output stops shrinking. Typically converges in 3 sweeps.
 
@@ -44,7 +45,7 @@ Runs passes in fixed-point sweeps until the output stops shrinking. Typically co
 Install with cargo:
 
 ```sh
-cargo install nagami --features cli
+cargo install nagami
 ```
 
 Example usage:
@@ -52,10 +53,13 @@ Example usage:
 ```sh
 nagami shader.wgsl -o shader.min.wgsl               # minify (max profile by default)
 nagami shader.wgsl --in-place --stats               # in-place, print savings
-nagami shader.wgsl -o out.wgsl -p baseline          # lighter touch, no mangle
+nagami shader.wgsl -o out.wgsl -p baseline          # DCE + folding only
 cat shader.wgsl | nagami - > out.wgsl               # stdin -> stdout
 nagami shader.wgsl --check                          # exit 1 if not minified
 nagami shader.wgsl --preamble env.wgsl -o out.wgsl  # external declarations
+nagami shader.wgsl -o out.wgsl --name-map map.json  # original -> final identifier map
+nagami shader.wgsl --format json                    # one JSON document on stdout
+nagami shader.wgsl -o out.wgsl --strict-fallback    # fail instead of shipping a text-only bailout
 nagami shader.wgsl --decimal-places 6 -o out.wgsl   # lossy: cap fractional digits
 nagami shader.wgsl --sig-figs 4 -o out.wgsl         # lossy: cap significant figures
 ```
@@ -70,16 +74,16 @@ Three optimization profiles control which IR passes run. Generator-level optimiz
 | Constant folding | ✓ | ✓ | ✓ |
 | Dead parameter elimination | ✓ | ✓ | ✓ |
 | Emit merge | ✓ | ✓ | ✓ |
-| Rename (preserve names) | ✓ | ✓ | ✓ |
+| Identifier renaming (globals, functions, params, locals) | ✓ | ✓ | ✓ |
 | Function inlining | - | ✓ (24 nodes / 3 call sites) | ✓ (48 nodes / 6 call sites) |
 | Load dedup + dead stores | - | ✓ | ✓ |
 | Variable coalescing | - | ✓ | ✓ |
 | Struct-build coalescing | - | ✓ | ✓ |
-| Vector-constant hoisting | - | ✓ | ✓ |
+| Vector-constant hoisting | - | - | ✓ |
 | Common subexpression elim | - | - | ✓ |
-| Identifier mangling | - | - | ✓ |
+| Mangling (struct types/members, constants, overrides) | - | - | ✓ |
 
-Passes run in fixed-point sweeps (up to 16) until the output stops shrinking. `baseline` is fast and safe; `aggressive` adds the full IR pipeline without mangling; `max` enables CSE and raises inlining limits for maximum compression.
+The `baseline` is fast and safe; `aggressive` adds the full IR pipeline without mangling; `max` raises inlining limits and enables CSE and vector-constant hoisting (both only while mangling is on) for maximum compression. `--no-mangle` disables mangling in any profile.
 
 ## Preamble
 
@@ -102,14 +106,14 @@ Preamble names are automatically preserved from renaming so that member access e
 Install with cargo:
 
 ```sh
-cargo add nagami
+cargo add nagami --no-default-features
 ```
 
 Run with default config:
 
 ```rust
 let output = nagami::run(src, &nagami::config::Config::default())?;
-println!("{}", output.source); // smol shader
+println!("{}", output.source);
 ```
 
 With a preamble (external declarations excluded from output):
@@ -134,10 +138,15 @@ Browser / bundler:
 
 ```js
 import init, { run } from 'nagami-rs';
-await init(); // load the WASM module once
-const { source, report } = run(shader);
-console.log(source); // minified WGSL
-console.log(report); // optimization report
+await init();          // load the WASM module once
+const { source, report, nameMap } = run(shader);
+console.log(source);   // minified WGSL
+console.log(report);   // optimization report; report.bailout holds naga's
+                       // error when the output is text-compacted only
+console.log(nameMap);  // original -> final names for bindings, functions,
+                       // overrides, entry points, struct members; null when
+                       // the shipped text is not the generator's output
+                       // (bailout, emitter fallback, input already smaller)
 ```
 
 With config (all fields optional):
@@ -145,7 +154,7 @@ With config (all fields optional):
 ```js
 const { source, report } = run(shader, {
   profile: 'max',             // "baseline" | "aggressive" | "max" (default)
-  mangle: true,               // rename identifiers (default: on for "max")
+  mangle: true,               // also rename struct types/members, constants, overrides (default: on for "max")
   preserveSymbols: ['main'],  // names to keep untouched
   beautify: false,            // compact output (default: false)
   indent: 2,                  // spaces per level when beautify is true
@@ -153,20 +162,20 @@ const { source, report } = run(shader, {
                               // also accepts { decimalPlaces: 6 }, { significantFigures: 4 },
                               // or per-type: { f32: 6, f64: { significantFigures: 12 } }
   maxInlineNodeCount: 48,     // inlining budget per function
-  maxInlineCallSites: 6,      // inlining budget per call site
+  maxInlineCallSites: 6,      // max call sites a function may have and still inline
   preamble: preambleSrc,      // external decls prepended for parsing, stripped from output
   validateEachPass: false,    // re-validate WGSL after every pass
 });
 ```
 
-Node.js (synchronous init):
+Node.js 20.6+ (synchronous init):
 
 ```js
 import { readFileSync } from 'node:fs';
 import { initSync, run } from 'nagami-rs';
 const wasm = readFileSync(new URL('nagami_bg.wasm', import.meta.resolve('nagami-rs')));
 initSync({ module: wasm });
-const { source, report } = run(shader); // or with config as above
+const { source, report } = run(shader);
 ```
 
 ## License

package/nagami.d.ts

@@ -46,12 +46,29 @@ export interface Report {
     outputBytes: number;
     converged: boolean;
     sweeps: number;
+    /** naga's error when the output is the input lexically compacted only. */
+    bailout: string | null;
     passReports: PassReport[];
 }
 
+export interface StructRename {
+    name: string;
+    members: Record<string, string>;
+}
+
+export interface NameMap {
+    entryPoints: Record<string, string>;
+    globals: Record<string, string>;
+    functions: Record<string, string>;
+    constants: Record<string, string>;
+    overrides: Record<string, string>;
+    structs: Record<string, StructRename>;
+}
+
 export interface Output {
     source: string;
     report: Report;
+    nameMap: NameMap | null;
 }
 
 export function run(source: string, config?: Config): Output;
@@ -60,12 +77,9 @@ export function version(): string;
 
 
 /**
- * Route Rust panic info to `console.error` at module instantiation:
- * under `panic = "abort"` the hook still runs first, so browsers get
- * the panic text and file:line instead of an opaque
- * `RuntimeError: unreachable executed`.  Hand-rolled because the
- * `console_error_panic_hook` crate adds only a JS stack trace of
- * mangled wasm frame indices.
+ * Panic text to `console.error`: under `panic = "abort"` the hook still runs
+ * first, so browsers see the message instead of `RuntimeError: unreachable`.
+ * Hand-rolled; `console_error_panic_hook` adds only mangled wasm frames.
  */
 export function install_panic_hook(): void;
 

package/nagami.js

@@ -1,25 +1,19 @@
 /* @ts-self-types="./nagami.d.ts" */
 
 /**
- * Route Rust panic info to `console.error` at module instantiation:
- * under `panic = "abort"` the hook still runs first, so browsers get
- * the panic text and file:line instead of an opaque
- * `RuntimeError: unreachable executed`.  Hand-rolled because the
- * `console_error_panic_hook` crate adds only a JS stack trace of
- * mangled wasm frame indices.
+ * Panic text to `console.error`: under `panic = "abort"` the hook still runs
+ * first, so browsers see the message instead of `RuntimeError: unreachable`.
+ * Hand-rolled; `console_error_panic_hook` adds only mangled wasm frames.
  */
 export function install_panic_hook() {
     wasm.install_panic_hook();
 }
 
 /**
- * Minify a WGSL source string.  Returns a JS object matching the
- * TypeScript `Output` interface declared below.
- *
- * # Errors
- *
- * Propagates any [`crate::error::Error`] from the pipeline as a
- * [`JsError`] carrying the rendered message.
+ * Minify `source` into the parsed [`crate::json`] document (TS `Output`).
+ * Errors are thrown JS `Error`s; a `JSON.parse` rejection (unreachable, the
+ * renderer emits valid JSON) propagates as its own `SyntaxError`, which keeps
+ * `JsValue`'s `Debug` glue out of the bundle.
  * @param {string} source
  * @param {any} config
  * @returns {any}
@@ -43,7 +37,7 @@ export function run(source, config) {
 }
 
 /**
- * Return the `CARGO_PKG_VERSION` baked into the wasm bundle.
+ * Crate version baked into the bundle.
  * @returns {string}
  */
 export function version() {
@@ -104,7 +98,7 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_bb96b2010945f0bc: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_error_7f1e71fe68e5559e: function(arg0, arg1) {
+        __wbg_error_82407668d9111acb: function(arg0, arg1) {
             console.error(getStringFromWasm0(arg0, arg1));
         },
         __wbg_get_971a0c45d172643f: function() { return handleError(function (arg0, arg1) {
@@ -123,28 +117,11 @@ function __wbg_get_imports() {
             const ret = getObject(arg0).length;
             return ret;
         },
-        __wbg_new_116be93542d39019: function() {
-            const ret = new Array();
+        __wbg_parse_1cc93481b0865939: function() { return handleError(function (arg0, arg1) {
+            const ret = JSON.parse(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
-        },
-        __wbg_new_ebe3e0f6837f0879: function() {
-            const ret = new Object();
-            return addHeapObject(ret);
-        },
-        __wbg_push_adb0107829f02d75: function(arg0, arg1) {
-            const ret = getObject(arg0).push(getObject(arg1));
-            return ret;
-        },
-        __wbg_set_8155bb79a948541b: function() { return handleError(function (arg0, arg1, arg2) {
-            const ret = Reflect.set(getObject(arg0), getObject(arg1), getObject(arg2));
-            return ret;
         }, arguments); },
-        __wbindgen_cast_0000000000000001: function(arg0) {
-            // Cast intrinsic for `F64 -> Externref`.
-            const ret = arg0;
-            return addHeapObject(ret);
-        },
-        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return addHeapObject(ret);

package/package.json

@@ -2,7 +2,7 @@
   "name": "nagami-rs",
   "type": "module",
   "description": "Shrinks WGSL shaders via Naga IR optimization passes",
-  "version": "2026.7.2",
+  "version": "2026.9.1",
   "license": "MIT",
   "repository": {
     "type": "git",