@forgeax/engine-naga 0.1.2

package/src/__tests__/reflect-uv-set-count.test.ts

@@ -0,0 +1,166 @@
+// feat-20260629-multi-uv-set-support m4-w1: naga reflection uvSetCount unit test.
+//
+// Tests that naga emit_reflection returns uvSetCount derived from vertex
+// @location declarations (D-4 convention: uv0 at location 2, uv1..7 at
+// location 6..12, counting only vec2<f32> vertex input arguments).
+//
+// This test calls through the real @forgeax/engine-naga TS wrapper (parse
+// -> validate -> emit_reflection), not mocked wasm. It starts RED because
+// the current emit_reflection (pre m4-w2) does not include uvSetCount in
+// the reflection JSON output. After m4-w2 (naga.rs modification) + m4-w4
+// (wasm rebuild), this test should go GREEN.
+//
+// Wgsl snippets avoid trailing commas inside struct definitions (WGSL
+// spec permits them but being conservative avoids naga parser edge cases).
+
+import { describe, expect, it } from 'vitest';
+import { emit_reflection, parse, validate } from '../index.js';
+
+// --- wgsl test fixtures --------------------------------------------------
+
+const WGSL_UV0_ONLY = `\
+struct VsIn {
+  @location(0) pos: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) tangent: vec4<f32>
+};
+@vertex fn vs(in: VsIn) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(0.0);
+}
+@fragment fn fs() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0);
+}`;
+
+const WGSL_UV0_UV1 = `\
+struct VsIn {
+  @location(0) pos: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) tangent: vec4<f32>,
+  @location(6) uv1: vec2<f32>
+};
+@vertex fn vs(in: VsIn) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(0.0);
+}
+@fragment fn fs() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0);
+}`;
+
+const WGSL_UV0_UV1_UV2 = `\
+struct VsIn {
+  @location(0) pos: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) tangent: vec4<f32>,
+  @location(6) uv1: vec2<f32>,
+  @location(7) uv2: vec2<f32>
+};
+@vertex fn vs(in: VsIn) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(0.0);
+}
+@fragment fn fs() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0);
+}`;
+
+const WGSL_UV0_SKIP_UV7 = `\
+struct VsIn {
+  @location(0) pos: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) tangent: vec4<f32>,
+  @location(8) uv3: vec2<f32>
+};
+@vertex fn vs(in: VsIn) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(0.0);
+}
+@fragment fn fs() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0);
+}`;
+
+// Also test a skin-aware WGSL with 0 extra UV
+const WGSL_SKIN_UV0_ONLY = `\
+struct VsIn {
+  @location(0) pos: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) tangent: vec4<f32>,
+  @location(4) skinIndex: vec4<u32>,
+  @location(5) skinWeight: vec4<f32>
+};
+@vertex fn vs(in: VsIn) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(0.0);
+}
+@fragment fn fs() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0);
+}`;
+
+// --- test body -----------------------------------------------------------
+
+describe('reflect-uv-set-count.test.ts', () => {
+  interface ReflectionOutput {
+    bindings: unknown;
+    uvSetCount: number;
+    material: {
+      members: unknown[];
+      resources: unknown[];
+      totalBytes: number;
+    };
+  }
+
+  async function reflectWgsl(wgsl: string): Promise<ReflectionOutput> {
+    const parsed = await parse(wgsl);
+    if (!parsed.ok) throw new Error(`parse failed: ${parsed.error.message}`);
+    const validated = await validate(parsed.value);
+    if (!validated.ok) throw new Error(`validate failed: ${validated.error.message}`);
+    const reflection = await emit_reflection(validated.value, '{}');
+    if (!reflection.ok) throw new Error(`emit_reflection failed: ${reflection.error.message}`);
+    const parsedObj = JSON.parse(reflection.value);
+    // After m4-w2 the reflection JSON format is { bindings: [...], uvSetCount: N }.
+    if (Array.isArray(parsedObj)) {
+      throw new Error(
+        'Reflection output is still the old array format; m4-w2 naga.rs changes not yet applied or wasm not rebuilt.',
+      );
+    }
+    return parsedObj as ReflectionOutput;
+  }
+
+  describe('naga emit_reflection uvSetCount derivation (D-4: uv0@loc2, extra@loc6+)', () => {
+    it('uv0 only -> uvSetCount=1', async () => {
+      const r = await reflectWgsl(WGSL_UV0_ONLY);
+      expect(r.uvSetCount).toBe(1);
+      expect(Array.isArray(r.bindings)).toBe(true);
+    });
+
+    it('uv0 + uv1 (locations 2 and 6) -> uvSetCount=2', async () => {
+      const r = await reflectWgsl(WGSL_UV0_UV1);
+      expect(r.uvSetCount).toBe(2);
+    });
+
+    it('uv0 + uv1 + uv2 (locations 2, 6, 7) -> uvSetCount=3', async () => {
+      const r = await reflectWgsl(WGSL_UV0_UV1_UV2);
+      expect(r.uvSetCount).toBe(3);
+    });
+
+    it('uv0 + skip to uv3 at location 8 -> uvSetCount=4 (max(location>=6)-5=3 extra)', async () => {
+      const r = await reflectWgsl(WGSL_UV0_SKIP_UV7);
+      // Per D-4 jump convention: max(location>=6) = 8, so uvSetCount = 1 + (8-5) = 4.
+      // The shader declares uv3 at @location(8) which implies uv1(loc6) and
+      // uv2(loc7) also exist in the packing convention even if not physically
+      // present in VsIn — clamp-to-last handles the gap.
+      expect(r.uvSetCount).toBe(4);
+    });
+
+    it('skin shader with uv0 only -> uvSetCount=1 (skinIndex/skinWeight not counted as UV)', async () => {
+      const r = await reflectWgsl(WGSL_SKIN_UV0_ONLY);
+      expect(r.uvSetCount).toBe(1);
+    });
+  });
+
+  it('raw reflection exposes a separate material region alongside engine bindings', async () => {
+    const r = await reflectWgsl(WGSL_UV0_ONLY);
+    expect(r).toHaveProperty('material');
+    expect(r).toHaveProperty('bindings');
+    expect(r.material).not.toBe(r.bindings);
+  });
+});

package/src/errors.ts

@@ -0,0 +1,208 @@
+// @forgeax/engine-naga/errors — ShaderError + Result<T, E> + wrapShaderError helper.
+//
+// Form invariants (plan-strategy §D-P4 / requirements MVP-2.3 + AC-09):
+// - ShaderErrorCode (closed 4-member union) is imported from @forgeax/engine-types as
+//   the SSOT. This package does **not** redefine the union — +0 breaking points
+//   to the error model (AC-09; charter proposition 5 consistent abstraction).
+// - The ShaderError class shape + 4 factory helpers + Result<T, E> shape are
+//   byte-for-byte equivalent to @forgeax/engine-shader-compiler/src/errors.ts; that
+//   package will re-export from here in w7 after the import switch lands
+//   (charter proposition 5 + plan-strategy D-P4 byte-for-byte form recovery).
+// - wrapShaderError is the JsError -> ShaderError adapter for the parse /
+//   validate / emit_reflection wrappers in index.ts: it tries to JSON.parse the
+//   wasm-side ParseErrorPayload (message / summary / line_num / line_pos)
+//   first, falls back to the prose message for validator / reflection failures.
+
+/// <reference types="@webgpu/types" />
+
+import type { ShaderErrorCode, ShaderErrorDetail } from '@forgeax/engine-types';
+
+export type { ShaderErrorCode, ShaderErrorDetail };
+
+interface ShaderErrorInit {
+  readonly code: ShaderErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly message: string;
+  readonly lineNum?: number | undefined;
+  readonly linePos?: number | undefined;
+  readonly detail?: ShaderErrorDetail | undefined;
+}
+
+/**
+ * Structured shader error.
+ *
+ * **5 surface fields** (MVP-2.3 top-level surface, AI consumer path):
+ * - `.code` — member of the closed `ShaderErrorCode` union (4 variants)
+ * - `.message` — display text (the base `Error` field, populated by the constructor)
+ * - `.hint` — actionable recovery guidance (charter proposition 3: machine-readable hint over prose)
+ * - `.lineNum` / `.linePos` — error source location (mandatory for compile-failed; undefined on other paths)
+ *
+ * **3 internal fields**:
+ * - `.name` = `'ShaderError'` (debug tag)
+ * - `.expected` — description of the expected state (symmetric with RhiError)
+ * - `.detail` — path-specific extra info (e.g. all 6 fields of GPUCompilationMessage[])
+ *
+ * **Do not new directly** — construct via the 4 factories (compileFailed /
+ * initFailed / manifestMalformed / shaderNotFound) to avoid ad-hoc arguments
+ * bypassing union narrowing.
+ */
+export class ShaderError extends Error {
+  override readonly name: 'ShaderError' = 'ShaderError';
+  readonly code: ShaderErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly lineNum: number | undefined;
+  readonly linePos: number | undefined;
+  readonly detail: ShaderErrorDetail | undefined;
+
+  constructor(init: ShaderErrorInit) {
+    super(init.message);
+    this.code = init.code;
+    this.expected = init.expected;
+    this.hint = init.hint;
+    this.lineNum = init.lineNum;
+    this.linePos = init.linePos;
+    this.detail = init.detail;
+  }
+}
+
+// === 4 factory helpers (plan-strategy §D-P4 closed union with 4 members) ===========
+
+/** `shader-compile-failed`: naga parse_str or Validator::validate failure. */
+export function compileFailed(args: {
+  readonly message: string;
+  readonly hint: string;
+  readonly lineNum?: number | undefined;
+  readonly linePos?: number | undefined;
+  readonly compilerMessages?: readonly GPUCompilationMessage[] | undefined;
+  readonly reason?: string | undefined;
+}): ShaderError {
+  return new ShaderError({
+    code: 'shader-compile-failed',
+    expected: 'WGSL source parses + validates against naga IR',
+    message: args.message,
+    hint: args.hint,
+    ...(args.lineNum !== undefined ? { lineNum: args.lineNum } : {}),
+    ...(args.linePos !== undefined ? { linePos: args.linePos } : {}),
+    ...(args.compilerMessages !== undefined
+      ? {
+          detail: {
+            code: 'shader-compile-failed',
+            compilerMessages: args.compilerMessages,
+            ...(args.reason !== undefined ? { reason: args.reason } : {}),
+          },
+        }
+      : {}),
+  });
+}
+
+/** `compiler-init-failed`: wasm loading or init() failure (cold start / missing wasm artifact). */
+export function initFailed(args: {
+  readonly message: string;
+  readonly hint: string;
+  readonly reason?: string | undefined;
+}): ShaderError {
+  return new ShaderError({
+    code: 'compiler-init-failed',
+    expected: '@forgeax/engine-wgpu-wasm ensureReady() resolves with naga raw bindings available',
+    message: args.message,
+    hint: args.hint,
+    detail: {
+      code: 'compiler-init-failed',
+      ...(args.reason !== undefined ? { reason: args.reason } : {}),
+    },
+  });
+}
+
+/** `manifest-malformed`: manifest.json schema validation failure (a required field is missing or JSON is not parseable). */
+export function manifestMalformed(args: {
+  readonly message: string;
+  readonly hint: string;
+  readonly reason?: string | undefined;
+}): ShaderError {
+  return new ShaderError({
+    code: 'manifest-malformed',
+    expected: 'manifest.json parses + every entry has {hash, wgsl, glsl, bindings}',
+    message: args.message,
+    hint: args.hint,
+    detail: {
+      code: 'manifest-malformed',
+      ...(args.reason !== undefined ? { reason: args.reason } : {}),
+    },
+  });
+}
+
+/** `shader-not-found`: ShaderRegistry.get(hash) hash miss. */
+export function shaderNotFound(args: {
+  readonly hash: string;
+  readonly hint: string;
+}): ShaderError {
+  return new ShaderError({
+    code: 'shader-not-found',
+    expected: `manifest.entries contains entry with hash '${args.hash}'`,
+    message: `ShaderRegistry: hash '${args.hash}' not present in manifest`,
+    hint: args.hint,
+  });
+}
+
+// === wrapShaderError: JsError -> ShaderError adapter ================================
+
+/**
+ * Translate a thrown wasm-bindgen JsError to a structured ShaderError.
+ *
+ * The Rust side serializes `ParseErrorPayload { message, summary, line_num,
+ * line_pos }` to a JSON string and uses it as the JsError message. We attempt
+ * JSON.parse first; on success the lineNum/linePos are extracted as top-level
+ * surface fields (MVP-2.3). On failure (validator errors, reflection errors,
+ * non-JSON messages) we fall back to the prose message — hint is always
+ * populated so AI consumers always have an actionable recovery signal
+ * (charter proposition 4 explicit failure + proposition 3 machine-readable hint).
+ */
+export function wrapShaderError(e: unknown, hint?: string): ShaderError {
+  if (e instanceof Error) {
+    try {
+      const payload = JSON.parse(e.message) as {
+        message?: string;
+        summary?: string;
+        line_num?: number | null;
+        line_pos?: number | null;
+      };
+      return compileFailed({
+        message: payload.summary ?? payload.message ?? e.message,
+        hint:
+          hint ??
+          'fix the WGSL source at the indicated line/column; see ShaderError.detail.compilerMessages for full diagnostic frame',
+        ...(typeof payload.line_num === 'number' ? { lineNum: payload.line_num } : {}),
+        ...(typeof payload.line_pos === 'number' ? { linePos: payload.line_pos } : {}),
+      });
+    } catch {
+      return compileFailed({
+        message: e.message,
+        hint: hint ?? 'check WGSL syntax + validation rules; consult naga error output for details',
+      });
+    }
+  }
+  return compileFailed({
+    message: String(e),
+    hint:
+      hint ??
+      'unknown error type from @forgeax/engine-wgpu-wasm; report as @forgeax/engine-naga bug',
+  });
+}
+
+// === Result<T, E> ====================================================================
+//
+// Result<T, E> + ok / err + ResultOk / ResultErr live in `@forgeax/engine-types`
+// (tweak-20260612-result-into-types). They were duplicated here as a lite
+// (plain-object, no `unwrap`) variant; consolidated upstream into the same
+// shape used by rhi / ecs. The barrel here re-exports them so existing
+// `import { err, ok, Result, ResultOk, ResultErr } from '@forgeax/engine-naga'`
+// consumers stay unchanged.
+export {
+  err,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+} from '@forgeax/engine-types';

package/src/index.ts

@@ -0,0 +1,230 @@
+// @forgeax/engine-naga — TS-only thin shell over @forgeax/engine-wgpu-wasm raw naga bindings.
+//
+// Form invariants (locked by plan-strategy D-P3 / D-P4 + research F-4):
+//
+// - snake_case three-phase functions byte-for-byte aligned with naga upstream
+//   naming (this package replaces the legacy wasm-pack shim archived in
+//   feat-20260511-naga-rhi-wgpu-merge M5 — charter proposition 2 industry
+//   analogy + proposition 5 consistent abstraction).
+// - Each public function awaits ensureReady() from @forgeax/engine-wgpu-wasm before
+//   calling the raw wasm-bindgen export — one wasm boundary crossing per page
+//   lifecycle, shared with @forgeax/engine-rhi-wgpu (research F-4 ensureReady SSOT).
+// - Throws are caught at the wrapper boundary and translated to
+//   Result.err(ShaderError) — never throw for expected failures
+//   (AGENTS.md "Errors are structured" + charter proposition 4 explicit failure).
+// - The opaque handle types ParsedModule / ValidatedModule are re-exported
+//   so downstream consumers (@forgeax/engine-shader-compiler) can hold the handle
+//   between phases without inspecting the underlying naga IR
+//   (plan-strategy §S-1 opaque handle invariant).
+
+import { ensureReady } from '@forgeax/engine-wgpu-wasm';
+import { err, ok, type Result, type ShaderError, wrapShaderError } from './errors.js';
+
+export {
+  compileFailed,
+  err,
+  initFailed,
+  manifestMalformed,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+  ShaderError,
+  type ShaderErrorCode,
+  type ShaderErrorDetail,
+  shaderNotFound,
+} from './errors.js';
+
+// === Opaque handle types ============================================================
+
+/**
+ * Handle for the `parse` output. The underlying type is a wasm-bindgen exported
+ * struct: JS can only hold the handle — it cannot inspect naga IR fields
+ * directly (charter proposition 4 + opaque handle invariant). Pass through to
+ * `validate` to advance to phase 2.
+ *
+ * Surface type uses `unknown` to keep this layer math-free and opaque-handle
+ * pure (no direct dependency on @forgeax/engine-wgpu-wasm/pkg ABI types). Downstream
+ * consumers should not inspect the handle.
+ */
+export type ParsedModule = unknown;
+
+/**
+ * Handle for the `validate` output (Module + ModuleInfo); pass through to
+ * `emit_reflection` for the reflection JSON emit.
+ */
+export type ValidatedModule = unknown;
+
+/** Structured material facts emitted by the independent raw Naga reflection. */
+export interface RawMaterialMemberFact {
+  readonly name: string;
+  readonly type: string;
+  readonly offset: number;
+  readonly size: number;
+  readonly alignment: number;
+}
+
+export interface RawMaterialResourceFact {
+  readonly name: string;
+  readonly kind: 'sampler' | 'texture' | 'storage-buffer';
+  readonly binding: number;
+}
+
+export interface RawMaterialReflectionFacts {
+  readonly members: readonly RawMaterialMemberFact[];
+  readonly resources: readonly RawMaterialResourceFact[];
+  readonly totalBytes: number;
+}
+
+// === Phase 1: parse =================================================================
+
+/**
+ * WGSL source -> `ParsedModule`.
+ *
+ * On failure returns `Result.err(ShaderError code='shader-compile-failed')`
+ * whose `lineNum` / `linePos` carry the source position (from the wasm-side
+ * `ParseErrorPayload`). The hint defaults to actionable WGSL fix guidance.
+ *
+ * Wasm boundary: awaits ensureReady() on first call (shared singleton with
+ * @forgeax/engine-rhi-wgpu); subsequent calls take the cached path.
+ */
+export async function parse(source: string): Promise<Result<ParsedModule, ShaderError>> {
+  let wasm: Awaited<ReturnType<typeof ensureReady>>;
+  try {
+    wasm = await ensureReady();
+  } catch (e) {
+    return err(
+      wrapShaderError(
+        e,
+        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',
+      ),
+    );
+  }
+  try {
+    const parsed = wasm.parse(source);
+    return ok(parsed as ParsedModule);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}
+
+// === Phase 2: validate ==============================================================
+
+/**
+ * `ParsedModule` -> `ValidatedModule` (Module + ModuleInfo).
+ *
+ * **Ownership transfer** — wasm-bindgen consumes the `parsed` handle. Do not
+ * reuse the handle after this call; passing a consumed handle is undefined
+ * behaviour on the wasm side (research Finding 6 ownership semantics).
+ *
+ * On failure returns `Result.err(ShaderError code='shader-compile-failed')`.
+ * Validator errors have no source position attached on the wasm side, so
+ * `lineNum` / `linePos` remain undefined.
+ */
+export async function validate(
+  parsed: ParsedModule,
+): Promise<Result<ValidatedModule, ShaderError>> {
+  let wasm: Awaited<ReturnType<typeof ensureReady>>;
+  try {
+    wasm = await ensureReady();
+  } catch (e) {
+    return err(
+      wrapShaderError(
+        e,
+        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',
+      ),
+    );
+  }
+  try {
+    const validated = (wasm.validate as (p: unknown) => unknown)(parsed);
+    return ok(validated as ValidatedModule);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}
+
+// === Composer passthrough ===========================================================
+
+/**
+ * naga_oil Composer passthrough — `#import` + `#ifdef` composition over WGSL.
+ *
+ * Thin TS wrap over `@forgeax/engine-wgpu-wasm`'s raw `compose_shader` export
+ * (feat-20260512 M1 compose.rs). Three-argument surface:
+ *
+ * - `entry` — the entry-point WGSL source (may contain `#import` directives
+ *   and `#ifdef` guards).
+ * - `imports` — `moduleId -> wgslSource` map; each value is a companion
+ *   module whose header declares `#define_import_path <moduleId>` so the
+ *   upstream composer can register it. The map is JSON.stringified at the
+ *   wasm boundary.
+ * - `defines` — `name -> boolean` map driving `#ifdef` branch elimination
+ *   (plan-strategy D-06: non-boolean values are rejected at the TS layer by
+ *   the shader-compiler wrapper; this wrap takes booleans verbatim). Also
+ *   JSON.stringified at the boundary.
+ *
+ * Return: the composed WGSL string (entry + inlined imports, `#ifdef` branches
+ * resolved).
+ *
+ * Errors: the raw wasm export throws `JsError` whose message carries a
+ * `shader-import-not-found: ...` or `shader-compile-failed: ...` prefix
+ * (feat-20260512 M1 compose.rs convention). This wrap does **not** translate
+ * the prefix into a structured `ShaderError`; that splitting happens one layer
+ * up at `@forgeax/engine-shader-compiler` (feat-20260512 M3), which is where
+ * the three-argument `compileShader(src, { imports, defines, id })` entry lives.
+ * Callers of this raw passthrough should `try / catch` the thrown error.
+ *
+ * Wasm boundary: awaits `ensureReady()` on first call (shared singleton with
+ * `@forgeax/engine-rhi-wgpu` + other naga phases); subsequent calls take the
+ * cached path.
+ */
+export async function composeShader(
+  entry: string,
+  imports: Record<string, string>,
+  defines: Record<string, boolean>,
+): Promise<string> {
+  const wasm = await ensureReady();
+  const compose = (wasm as { compose_shader: (e: string, i: string, d: string) => string })
+    .compose_shader;
+  return compose(entry, JSON.stringify(imports), JSON.stringify(defines));
+}
+
+// === Phase 3: emit_reflection =======================================================
+
+/**
+ * `ValidatedModule` + options JSON -> `BindGroupLayoutDescriptor[]` JSON string.
+ *
+ * `options_json` shape: `{ "dynamicOffsets": [{ "group": u32, "binding": u32 }, ...] }`.
+ * The naga IR does not express the dynamic-offset dimension (research Finding 2
+ * footnote), so it is injected via this JS-side options string. Pass an empty
+ * `{}` (or a JSON-encoded object without `dynamicOffsets`) for the no-dynamic-
+ * offset path.
+ *
+ * The validator's borrowed reference is **not** consumed — the same
+ * `ValidatedModule` handle can be reused for repeated emits with different
+ * options (e.g. for variant generation).
+ */
+export async function emit_reflection(
+  validated: ValidatedModule,
+  options_json: string,
+): Promise<Result<string, ShaderError>> {
+  let wasm: Awaited<ReturnType<typeof ensureReady>>;
+  try {
+    wasm = await ensureReady();
+  } catch (e) {
+    return err(
+      wrapShaderError(
+        e,
+        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',
+      ),
+    );
+  }
+  try {
+    const reflectionJson = (wasm.emit_reflection as (v: unknown, o: string) => string)(
+      validated,
+      options_json,
+    );
+    return ok(reflectionJson);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}