@forgeax/engine-naga 0.1.2

package/dist/index.mjs

@@ -0,0 +1,165 @@
+import { ensureReady } from '@forgeax/engine-wgpu-wasm';
+import { err, ok } from '@forgeax/engine-types';
+export { err, ok } from '@forgeax/engine-types';
+
+// src/index.ts
+var ShaderError = class extends Error {
+  name = "ShaderError";
+  code;
+  expected;
+  hint;
+  lineNum;
+  linePos;
+  detail;
+  constructor(init) {
+    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;
+  }
+};
+function compileFailed(args) {
+  return new ShaderError({
+    code: "shader-compile-failed",
+    expected: "WGSL source parses + validates against naga IR",
+    message: args.message,
+    hint: args.hint,
+    ...args.lineNum !== void 0 ? { lineNum: args.lineNum } : {},
+    ...args.linePos !== void 0 ? { linePos: args.linePos } : {},
+    ...args.compilerMessages !== void 0 ? {
+      detail: {
+        code: "shader-compile-failed",
+        compilerMessages: args.compilerMessages,
+        ...args.reason !== void 0 ? { reason: args.reason } : {}
+      }
+    } : {}
+  });
+}
+function initFailed(args) {
+  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 !== void 0 ? { reason: args.reason } : {}
+    }
+  });
+}
+function manifestMalformed(args) {
+  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 !== void 0 ? { reason: args.reason } : {}
+    }
+  });
+}
+function shaderNotFound(args) {
+  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
+  });
+}
+function wrapShaderError(e, hint) {
+  if (e instanceof Error) {
+    try {
+      const payload = JSON.parse(e.message);
+      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"
+  });
+}
+
+// src/index.ts
+async function parse(source) {
+  let wasm;
+  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);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}
+async function validate(parsed) {
+  let wasm;
+  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(parsed);
+    return ok(validated);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}
+async function composeShader(entry, imports, defines) {
+  const wasm = await ensureReady();
+  const compose = wasm.compose_shader;
+  return compose(entry, JSON.stringify(imports), JSON.stringify(defines));
+}
+async function emit_reflection(validated, options_json) {
+  let wasm;
+  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(
+      validated,
+      options_json
+    );
+    return ok(reflectionJson);
+  } catch (e) {
+    return err(wrapShaderError(e));
+  }
+}
+
+export { ShaderError, compileFailed, composeShader, emit_reflection, initFailed, manifestMalformed, parse, shaderNotFound, validate };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["// @forgeax/engine-naga/errors — ShaderError + Result<T, E> + wrapShaderError helper.\n//\n// Form invariants (plan-strategy §D-P4 / requirements MVP-2.3 + AC-09):\n// - ShaderErrorCode (closed 4-member union) is imported from @forgeax/engine-types as\n//   the SSOT. This package does **not** redefine the union — +0 breaking points\n//   to the error model (AC-09; charter proposition 5 consistent abstraction).\n// - The ShaderError class shape + 4 factory helpers + Result<T, E> shape are\n//   byte-for-byte equivalent to @forgeax/engine-shader-compiler/src/errors.ts; that\n//   package will re-export from here in w7 after the import switch lands\n//   (charter proposition 5 + plan-strategy D-P4 byte-for-byte form recovery).\n// - wrapShaderError is the JsError -> ShaderError adapter for the parse /\n//   validate / emit_reflection wrappers in index.ts: it tries to JSON.parse the\n//   wasm-side ParseErrorPayload (message / summary / line_num / line_pos)\n//   first, falls back to the prose message for validator / reflection failures.\n\n/// <reference types=\"@webgpu/types\" />\n\nimport type { ShaderErrorCode, ShaderErrorDetail } from '@forgeax/engine-types';\n\nexport type { ShaderErrorCode, ShaderErrorDetail };\n\ninterface ShaderErrorInit {\n  readonly code: ShaderErrorCode;\n  readonly expected: string;\n  readonly hint: string;\n  readonly message: string;\n  readonly lineNum?: number | undefined;\n  readonly linePos?: number | undefined;\n  readonly detail?: ShaderErrorDetail | undefined;\n}\n\n/**\n * Structured shader error.\n *\n * **5 surface fields** (MVP-2.3 top-level surface, AI consumer path):\n * - `.code` — member of the closed `ShaderErrorCode` union (4 variants)\n * - `.message` — display text (the base `Error` field, populated by the constructor)\n * - `.hint` — actionable recovery guidance (charter proposition 3: machine-readable hint over prose)\n * - `.lineNum` / `.linePos` — error source location (mandatory for compile-failed; undefined on other paths)\n *\n * **3 internal fields**:\n * - `.name` = `'ShaderError'` (debug tag)\n * - `.expected` — description of the expected state (symmetric with RhiError)\n * - `.detail` — path-specific extra info (e.g. all 6 fields of GPUCompilationMessage[])\n *\n * **Do not new directly** — construct via the 4 factories (compileFailed /\n * initFailed / manifestMalformed / shaderNotFound) to avoid ad-hoc arguments\n * bypassing union narrowing.\n */\nexport class ShaderError extends Error {\n  override readonly name: 'ShaderError' = 'ShaderError';\n  readonly code: ShaderErrorCode;\n  readonly expected: string;\n  readonly hint: string;\n  readonly lineNum: number | undefined;\n  readonly linePos: number | undefined;\n  readonly detail: ShaderErrorDetail | undefined;\n\n  constructor(init: ShaderErrorInit) {\n    super(init.message);\n    this.code = init.code;\n    this.expected = init.expected;\n    this.hint = init.hint;\n    this.lineNum = init.lineNum;\n    this.linePos = init.linePos;\n    this.detail = init.detail;\n  }\n}\n\n// === 4 factory helpers (plan-strategy §D-P4 closed union with 4 members) ===========\n\n/** `shader-compile-failed`: naga parse_str or Validator::validate failure. */\nexport function compileFailed(args: {\n  readonly message: string;\n  readonly hint: string;\n  readonly lineNum?: number | undefined;\n  readonly linePos?: number | undefined;\n  readonly compilerMessages?: readonly GPUCompilationMessage[] | undefined;\n  readonly reason?: string | undefined;\n}): ShaderError {\n  return new ShaderError({\n    code: 'shader-compile-failed',\n    expected: 'WGSL source parses + validates against naga IR',\n    message: args.message,\n    hint: args.hint,\n    ...(args.lineNum !== undefined ? { lineNum: args.lineNum } : {}),\n    ...(args.linePos !== undefined ? { linePos: args.linePos } : {}),\n    ...(args.compilerMessages !== undefined\n      ? {\n          detail: {\n            code: 'shader-compile-failed',\n            compilerMessages: args.compilerMessages,\n            ...(args.reason !== undefined ? { reason: args.reason } : {}),\n          },\n        }\n      : {}),\n  });\n}\n\n/** `compiler-init-failed`: wasm loading or init() failure (cold start / missing wasm artifact). */\nexport function initFailed(args: {\n  readonly message: string;\n  readonly hint: string;\n  readonly reason?: string | undefined;\n}): ShaderError {\n  return new ShaderError({\n    code: 'compiler-init-failed',\n    expected: '@forgeax/engine-wgpu-wasm ensureReady() resolves with naga raw bindings available',\n    message: args.message,\n    hint: args.hint,\n    detail: {\n      code: 'compiler-init-failed',\n      ...(args.reason !== undefined ? { reason: args.reason } : {}),\n    },\n  });\n}\n\n/** `manifest-malformed`: manifest.json schema validation failure (a required field is missing or JSON is not parseable). */\nexport function manifestMalformed(args: {\n  readonly message: string;\n  readonly hint: string;\n  readonly reason?: string | undefined;\n}): ShaderError {\n  return new ShaderError({\n    code: 'manifest-malformed',\n    expected: 'manifest.json parses + every entry has {hash, wgsl, glsl, bindings}',\n    message: args.message,\n    hint: args.hint,\n    detail: {\n      code: 'manifest-malformed',\n      ...(args.reason !== undefined ? { reason: args.reason } : {}),\n    },\n  });\n}\n\n/** `shader-not-found`: ShaderRegistry.get(hash) hash miss. */\nexport function shaderNotFound(args: {\n  readonly hash: string;\n  readonly hint: string;\n}): ShaderError {\n  return new ShaderError({\n    code: 'shader-not-found',\n    expected: `manifest.entries contains entry with hash '${args.hash}'`,\n    message: `ShaderRegistry: hash '${args.hash}' not present in manifest`,\n    hint: args.hint,\n  });\n}\n\n// === wrapShaderError: JsError -> ShaderError adapter ================================\n\n/**\n * Translate a thrown wasm-bindgen JsError to a structured ShaderError.\n *\n * The Rust side serializes `ParseErrorPayload { message, summary, line_num,\n * line_pos }` to a JSON string and uses it as the JsError message. We attempt\n * JSON.parse first; on success the lineNum/linePos are extracted as top-level\n * surface fields (MVP-2.3). On failure (validator errors, reflection errors,\n * non-JSON messages) we fall back to the prose message — hint is always\n * populated so AI consumers always have an actionable recovery signal\n * (charter proposition 4 explicit failure + proposition 3 machine-readable hint).\n */\nexport function wrapShaderError(e: unknown, hint?: string): ShaderError {\n  if (e instanceof Error) {\n    try {\n      const payload = JSON.parse(e.message) as {\n        message?: string;\n        summary?: string;\n        line_num?: number | null;\n        line_pos?: number | null;\n      };\n      return compileFailed({\n        message: payload.summary ?? payload.message ?? e.message,\n        hint:\n          hint ??\n          'fix the WGSL source at the indicated line/column; see ShaderError.detail.compilerMessages for full diagnostic frame',\n        ...(typeof payload.line_num === 'number' ? { lineNum: payload.line_num } : {}),\n        ...(typeof payload.line_pos === 'number' ? { linePos: payload.line_pos } : {}),\n      });\n    } catch {\n      return compileFailed({\n        message: e.message,\n        hint: hint ?? 'check WGSL syntax + validation rules; consult naga error output for details',\n      });\n    }\n  }\n  return compileFailed({\n    message: String(e),\n    hint:\n      hint ??\n      'unknown error type from @forgeax/engine-wgpu-wasm; report as @forgeax/engine-naga bug',\n  });\n}\n\n// === Result<T, E> ====================================================================\n//\n// Result<T, E> + ok / err + ResultOk / ResultErr live in `@forgeax/engine-types`\n// (tweak-20260612-result-into-types). They were duplicated here as a lite\n// (plain-object, no `unwrap`) variant; consolidated upstream into the same\n// shape used by rhi / ecs. The barrel here re-exports them so existing\n// `import { err, ok, Result, ResultOk, ResultErr } from '@forgeax/engine-naga'`\n// consumers stay unchanged.\nexport {\n  err,\n  ok,\n  type Result,\n  type ResultErr,\n  type ResultOk,\n} from '@forgeax/engine-types';\n","// @forgeax/engine-naga — TS-only thin shell over @forgeax/engine-wgpu-wasm raw naga bindings.\n//\n// Form invariants (locked by plan-strategy D-P3 / D-P4 + research F-4):\n//\n// - snake_case three-phase functions byte-for-byte aligned with naga upstream\n//   naming (this package replaces the legacy wasm-pack shim archived in\n//   feat-20260511-naga-rhi-wgpu-merge M5 — charter proposition 2 industry\n//   analogy + proposition 5 consistent abstraction).\n// - Each public function awaits ensureReady() from @forgeax/engine-wgpu-wasm before\n//   calling the raw wasm-bindgen export — one wasm boundary crossing per page\n//   lifecycle, shared with @forgeax/engine-rhi-wgpu (research F-4 ensureReady SSOT).\n// - Throws are caught at the wrapper boundary and translated to\n//   Result.err(ShaderError) — never throw for expected failures\n//   (AGENTS.md \"Errors are structured\" + charter proposition 4 explicit failure).\n// - The opaque handle types ParsedModule / ValidatedModule are re-exported\n//   so downstream consumers (@forgeax/engine-shader-compiler) can hold the handle\n//   between phases without inspecting the underlying naga IR\n//   (plan-strategy §S-1 opaque handle invariant).\n\nimport { ensureReady } from '@forgeax/engine-wgpu-wasm';\nimport { err, ok, type Result, type ShaderError, wrapShaderError } from './errors.js';\n\nexport {\n  compileFailed,\n  err,\n  initFailed,\n  manifestMalformed,\n  ok,\n  type Result,\n  type ResultErr,\n  type ResultOk,\n  ShaderError,\n  type ShaderErrorCode,\n  type ShaderErrorDetail,\n  shaderNotFound,\n} from './errors.js';\n\n// === Opaque handle types ============================================================\n\n/**\n * Handle for the `parse` output. The underlying type is a wasm-bindgen exported\n * struct: JS can only hold the handle — it cannot inspect naga IR fields\n * directly (charter proposition 4 + opaque handle invariant). Pass through to\n * `validate` to advance to phase 2.\n *\n * Surface type uses `unknown` to keep this layer math-free and opaque-handle\n * pure (no direct dependency on @forgeax/engine-wgpu-wasm/pkg ABI types). Downstream\n * consumers should not inspect the handle.\n */\nexport type ParsedModule = unknown;\n\n/**\n * Handle for the `validate` output (Module + ModuleInfo); pass through to\n * `emit_reflection` for the reflection JSON emit.\n */\nexport type ValidatedModule = unknown;\n\n/** Structured material facts emitted by the independent raw Naga reflection. */\nexport interface RawMaterialMemberFact {\n  readonly name: string;\n  readonly type: string;\n  readonly offset: number;\n  readonly size: number;\n  readonly alignment: number;\n}\n\nexport interface RawMaterialResourceFact {\n  readonly name: string;\n  readonly kind: 'sampler' | 'texture' | 'storage-buffer';\n  readonly binding: number;\n}\n\nexport interface RawMaterialReflectionFacts {\n  readonly members: readonly RawMaterialMemberFact[];\n  readonly resources: readonly RawMaterialResourceFact[];\n  readonly totalBytes: number;\n}\n\n// === Phase 1: parse =================================================================\n\n/**\n * WGSL source -> `ParsedModule`.\n *\n * On failure returns `Result.err(ShaderError code='shader-compile-failed')`\n * whose `lineNum` / `linePos` carry the source position (from the wasm-side\n * `ParseErrorPayload`). The hint defaults to actionable WGSL fix guidance.\n *\n * Wasm boundary: awaits ensureReady() on first call (shared singleton with\n * @forgeax/engine-rhi-wgpu); subsequent calls take the cached path.\n */\nexport async function parse(source: string): Promise<Result<ParsedModule, ShaderError>> {\n  let wasm: Awaited<ReturnType<typeof ensureReady>>;\n  try {\n    wasm = await ensureReady();\n  } catch (e) {\n    return err(\n      wrapShaderError(\n        e,\n        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',\n      ),\n    );\n  }\n  try {\n    const parsed = wasm.parse(source);\n    return ok(parsed as ParsedModule);\n  } catch (e) {\n    return err(wrapShaderError(e));\n  }\n}\n\n// === Phase 2: validate ==============================================================\n\n/**\n * `ParsedModule` -> `ValidatedModule` (Module + ModuleInfo).\n *\n * **Ownership transfer** — wasm-bindgen consumes the `parsed` handle. Do not\n * reuse the handle after this call; passing a consumed handle is undefined\n * behaviour on the wasm side (research Finding 6 ownership semantics).\n *\n * On failure returns `Result.err(ShaderError code='shader-compile-failed')`.\n * Validator errors have no source position attached on the wasm side, so\n * `lineNum` / `linePos` remain undefined.\n */\nexport async function validate(\n  parsed: ParsedModule,\n): Promise<Result<ValidatedModule, ShaderError>> {\n  let wasm: Awaited<ReturnType<typeof ensureReady>>;\n  try {\n    wasm = await ensureReady();\n  } catch (e) {\n    return err(\n      wrapShaderError(\n        e,\n        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',\n      ),\n    );\n  }\n  try {\n    const validated = (wasm.validate as (p: unknown) => unknown)(parsed);\n    return ok(validated as ValidatedModule);\n  } catch (e) {\n    return err(wrapShaderError(e));\n  }\n}\n\n// === Composer passthrough ===========================================================\n\n/**\n * naga_oil Composer passthrough — `#import` + `#ifdef` composition over WGSL.\n *\n * Thin TS wrap over `@forgeax/engine-wgpu-wasm`'s raw `compose_shader` export\n * (feat-20260512 M1 compose.rs). Three-argument surface:\n *\n * - `entry` — the entry-point WGSL source (may contain `#import` directives\n *   and `#ifdef` guards).\n * - `imports` — `moduleId -> wgslSource` map; each value is a companion\n *   module whose header declares `#define_import_path <moduleId>` so the\n *   upstream composer can register it. The map is JSON.stringified at the\n *   wasm boundary.\n * - `defines` — `name -> boolean` map driving `#ifdef` branch elimination\n *   (plan-strategy D-06: non-boolean values are rejected at the TS layer by\n *   the shader-compiler wrapper; this wrap takes booleans verbatim). Also\n *   JSON.stringified at the boundary.\n *\n * Return: the composed WGSL string (entry + inlined imports, `#ifdef` branches\n * resolved).\n *\n * Errors: the raw wasm export throws `JsError` whose message carries a\n * `shader-import-not-found: ...` or `shader-compile-failed: ...` prefix\n * (feat-20260512 M1 compose.rs convention). This wrap does **not** translate\n * the prefix into a structured `ShaderError`; that splitting happens one layer\n * up at `@forgeax/engine-shader-compiler` (feat-20260512 M3), which is where\n * the three-argument `compileShader(src, { imports, defines, id })` entry lives.\n * Callers of this raw passthrough should `try / catch` the thrown error.\n *\n * Wasm boundary: awaits `ensureReady()` on first call (shared singleton with\n * `@forgeax/engine-rhi-wgpu` + other naga phases); subsequent calls take the\n * cached path.\n */\nexport async function composeShader(\n  entry: string,\n  imports: Record<string, string>,\n  defines: Record<string, boolean>,\n): Promise<string> {\n  const wasm = await ensureReady();\n  const compose = (wasm as { compose_shader: (e: string, i: string, d: string) => string })\n    .compose_shader;\n  return compose(entry, JSON.stringify(imports), JSON.stringify(defines));\n}\n\n// === Phase 3: emit_reflection =======================================================\n\n/**\n * `ValidatedModule` + options JSON -> `BindGroupLayoutDescriptor[]` JSON string.\n *\n * `options_json` shape: `{ \"dynamicOffsets\": [{ \"group\": u32, \"binding\": u32 }, ...] }`.\n * The naga IR does not express the dynamic-offset dimension (research Finding 2\n * footnote), so it is injected via this JS-side options string. Pass an empty\n * `{}` (or a JSON-encoded object without `dynamicOffsets`) for the no-dynamic-\n * offset path.\n *\n * The validator's borrowed reference is **not** consumed — the same\n * `ValidatedModule` handle can be reused for repeated emits with different\n * options (e.g. for variant generation).\n */\nexport async function emit_reflection(\n  validated: ValidatedModule,\n  options_json: string,\n): Promise<Result<string, ShaderError>> {\n  let wasm: Awaited<ReturnType<typeof ensureReady>>;\n  try {\n    wasm = await ensureReady();\n  } catch (e) {\n    return err(\n      wrapShaderError(\n        e,\n        'rerun bash packages/wgpu-wasm/build.sh and verify packages/wgpu-wasm/pkg contains a fresh .wasm',\n      ),\n    );\n  }\n  try {\n    const reflectionJson = (wasm.emit_reflection as (v: unknown, o: string) => string)(\n      validated,\n      options_json,\n    );\n    return ok(reflectionJson);\n  } catch (e) {\n    return err(wrapShaderError(e));\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@forgeax/engine-naga",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "TS-only thin shell over @forgeax/engine-wgpu-wasm raw naga bindings — build-time shader pipeline tooling (parse / validate / emit_reflection). Consumed by @forgeax/engine-shader-compiler; AI engine users may import directly for WGSL syntax-check reuse.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-types": "0.1.2",
+    "@forgeax/engine-wgpu-wasm": "0.1.2",
+    "@webgpu/types": "^0.1.71"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": false,
+        "reason": "TS-only thin shell; physical wasm size measured at @forgeax/engine-wgpu-wasm workspace baseline. No standalone JS bundle size budget enforced at this layer."
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "build-time compiler shim; no runtime canvas"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "naga parse / validate / emit_reflection timing is shader-compile-time bench; pending feat-future-shader-compile-time"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "physical-isolation grep gates (check-shader-no-naga-in-dist + check-shader-runtime-deps + check-shader-no-compiler-import) are repo-root scripts wired into ci.yml lint job, not a per-package gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; productionised TS-only thin shell over @forgeax/engine-wgpu-wasm"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/naga.unit.test.ts

@@ -0,0 +1,335 @@
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: scope isolation between merged source files
+//
+// Source files (N=5):
+//   - packages/naga/src/__tests__/compose.test.ts
+//   - packages/naga/src/__tests__/emit_reflection.test.ts
+//   - packages/naga/src/__tests__/errors.test.ts
+//   - packages/naga/src/__tests__/parse.test.ts
+//   - packages/naga/src/__tests__/validate.test.ts
+//
+// Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
+// source as ancestorTitles[0]. Top-level imports merged + deduped.
+//
+// Naga packages share a common vi.mock('@forgeax/engine-wgpu-wasm') pattern.
+// Merged into one unified mock that provides all needed functions.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { compileFailed } from '../errors.js';
+
+const _parse = vi.fn();
+const _validate = vi.fn();
+const _emit_reflection = vi.fn();
+const _compose = vi.fn();
+
+vi.mock('@forgeax/engine-wgpu-wasm', () => ({
+  ensureReady: vi.fn(async () => ({
+    parse: _parse,
+    validate: _validate,
+    emit_reflection: _emit_reflection,
+    compose_shader: _compose,
+  })),
+}));
+
+{
+  // ─── from compose.test.ts ───
+
+  describe('compose.test.ts', () => {
+    describe('@forgeax/engine-naga composeShader wrapper', () => {
+      beforeEach(() => {
+        _compose.mockReset();
+        _parse.mockReset();
+        _validate.mockReset();
+        _emit_reflection.mockReset();
+        vi.resetModules();
+      });
+
+      afterEach(() => {
+        vi.clearAllMocks();
+      });
+
+      it('forwards entry + JSON-stringified imports + defines to wasm compose_shader and returns the composed WGSL string (basic #import happy path)', async () => {
+        const entry = [
+          '#import forgeax_pbr::brdf',
+          '@vertex fn vs() -> @builtin(position) vec4<f32> { return brdf::sample(); }',
+        ].join('\n');
+        const imports = {
+          'forgeax_pbr::brdf': [
+            '#define_import_path forgeax_pbr::brdf',
+            'fn sample() -> vec4<f32> { return vec4<f32>(0.0); }',
+          ].join('\n'),
+        };
+        const defines = { FOO: true };
+        const composed = '// composed wgsl\nfn sample() -> vec4<f32> { return vec4<f32>(0.0); }';
+        _compose.mockReturnValueOnce(composed);
+
+        const { composeShader } = await import('../index.js');
+        const out = await composeShader(entry, imports, defines);
+
+        expect(out).toBe(composed);
+        expect(_compose).toHaveBeenCalledTimes(1);
+        const call = _compose.mock.calls[0];
+        if (!call) throw new Error('compose_shader mock was not called');
+        const [forwardedEntry, forwardedImportsJson, forwardedDefinesJson] = call;
+        expect(forwardedEntry).toBe(entry);
+        expect(JSON.parse(forwardedImportsJson)).toEqual(imports);
+        expect(JSON.parse(forwardedDefinesJson)).toEqual(defines);
+      });
+
+      it('propagates shader-import-not-found: prefix error from wasm compose_shader JsError', async () => {
+        const entry =
+          '#import forgeax_missing::mod\n@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }';
+        _compose.mockImplementationOnce(() => {
+          throw new Error('shader-import-not-found: module forgeax_missing::mod not registered');
+        });
+
+        const { composeShader } = await import('../index.js');
+        await expect(composeShader(entry, {}, {})).rejects.toThrow(/shader-import-not-found:/);
+      });
+
+      it('passes #ifdef defines through to wasm so the upstream composer can eliminate branches (define=true branch retained; define=false branch dropped)', async () => {
+        const entry = [
+          '#ifdef WANT_FOO',
+          'fn foo() -> f32 { return 1.0; }',
+          '#endif',
+          '#ifdef WANT_BAR',
+          'fn bar() -> f32 { return 2.0; }',
+          '#endif',
+        ].join('\n');
+
+        const composed = 'fn foo() -> f32 { return 1.0; }';
+        _compose.mockReturnValueOnce(composed);
+
+        const { composeShader } = await import('../index.js');
+        const out = await composeShader(entry, {}, { WANT_FOO: true, WANT_BAR: false });
+
+        expect(out).toBe(composed);
+        const call = _compose.mock.calls[0];
+        if (!call) throw new Error('compose_shader mock was not called');
+        const [, , forwardedDefinesJson] = call;
+        expect(JSON.parse(forwardedDefinesJson)).toEqual({ WANT_FOO: true, WANT_BAR: false });
+      });
+    });
+  });
+}
+
+{
+  // ─── from emit_reflection.test.ts ───
+
+  describe('emit_reflection.test.ts', () => {
+    describe('@forgeax/engine-naga emit_reflection wrapper', () => {
+      beforeEach(() => {
+        _parse.mockReset();
+        _validate.mockReset();
+        _emit_reflection.mockReset();
+        vi.resetModules();
+      });
+
+      afterEach(() => {
+        vi.clearAllMocks();
+      });
+
+      it('returns Result.ok(reflectionJson) and forwards (validated, options_json) verbatim', async () => {
+        const validatedHandle = { _tag: 'ValidatedModule' };
+        const expectedJson = '[{"label":"@group(0)","entries":[]}]';
+        _emit_reflection.mockReturnValueOnce(expectedJson);
+        const optionsJson = JSON.stringify({ dynamicOffsets: [{ group: 0, binding: 0 }] });
+        const { emit_reflection } = await import('../index.js');
+        const r = await emit_reflection(validatedHandle, optionsJson);
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+          expect(r.value).toBe(expectedJson);
+        }
+        expect(_emit_reflection).toHaveBeenCalledWith(validatedHandle, optionsJson);
+      });
+
+      it('preserves structured material member and resource facts from raw reflection', async () => {
+        const expectedJson = JSON.stringify({
+          bindings: [],
+          uvSetCount: 0,
+          material: {
+            members: [
+              {
+                name: 'albedoCoordinatesTransform',
+                type: 'vec4<f32>',
+                offset: 0,
+                size: 16,
+                alignment: 16,
+              },
+            ],
+            resources: [{ name: 'albedo', kind: 'texture', binding: 2 }],
+            totalBytes: 16,
+          },
+        });
+        _emit_reflection.mockReturnValueOnce(expectedJson);
+        const { emit_reflection } = await import('../index.js');
+        const result = await emit_reflection({ _tag: 'ValidatedModule' }, '{}');
+
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+          expect(JSON.parse(result.value).material.members[0].offset).toBe(0);
+          expect(JSON.parse(result.value).material.resources[0].binding).toBe(2);
+        }
+      });
+
+      it('returns Result.err(ShaderError) with non-empty hint when raw emit_reflection throws', async () => {
+        _emit_reflection.mockImplementationOnce(() => {
+          throw new Error('reflection serialize failed: cyclic type graph');
+        });
+        const { emit_reflection } = await import('../index.js');
+        const r = await emit_reflection({ _tag: 'ValidatedModule' }, '{}');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+          expect(r.error.code).toBe('shader-compile-failed');
+          expect(r.error.message).toContain('cyclic type graph');
+          expect(r.error.hint).toBeTruthy();
+          expect(r.error.hint.length).toBeGreaterThan(0);
+        }
+      });
+    });
+  });
+}
+
+{
+  // ─── from errors.test.ts ───
+
+  describe('errors.test.ts', () => {
+    describe('compileFailed factory — D-PS-3 path (b) contract', () => {
+      it('compileFailed without compilerMessages keeps detail undefined', () => {
+        const err = compileFailed({
+          message: 'WGSL parse failed at line 3, column 5',
+          hint: 'fix the WGSL source at the indicated line/column',
+        });
+        expect(err.code).toBe('shader-compile-failed');
+        expect(err.detail).toBeUndefined();
+      });
+
+      it('compileFailed with compilerMessages constructs typed detail (regression smoke)', () => {
+        const err = compileFailed({
+          message: 'WGSL parse failed',
+          hint: 'see ShaderError.detail.compilerMessages',
+          compilerMessages: [],
+        });
+        expect(err.code).toBe('shader-compile-failed');
+        expect(err.detail).toBeDefined();
+      });
+    });
+  });
+}
+
+{
+  // ─── from parse.test.ts ───
+
+  describe('parse.test.ts', () => {
+    describe('@forgeax/engine-naga parse wrapper', () => {
+      beforeEach(() => {
+        _parse.mockReset();
+        _validate.mockReset();
+        _emit_reflection.mockReset();
+        vi.resetModules();
+      });
+
+      afterEach(() => {
+        vi.clearAllMocks();
+      });
+
+      it('returns Result.ok(opaque handle) when raw wasm parse succeeds', async () => {
+        const opaqueHandle = { _tag: 'ParsedModule' };
+        _parse.mockReturnValueOnce(opaqueHandle);
+        const { parse } = await import('../index.js');
+        const r = await parse(
+          '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        );
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+          expect(r.value).toBe(opaqueHandle);
+        }
+        expect(_parse).toHaveBeenCalledTimes(1);
+      });
+
+      it('returns Result.err(ShaderError code=shader-compile-failed) with lineNum/linePos when raw parse throws JsError with ParseErrorPayload', async () => {
+        const payload = {
+          message: "expected ';', found '@'",
+          summary: "expected ';', found '@' at line 3 col 12",
+          line_num: 3,
+          line_pos: 12,
+        };
+        _parse.mockImplementationOnce(() => {
+          throw new Error(JSON.stringify(payload));
+        });
+        const { parse } = await import('../index.js');
+        const r = await parse('invalid wgsl');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+          expect(r.error.code).toBe('shader-compile-failed');
+          expect(r.error.lineNum).toBe(3);
+          expect(r.error.linePos).toBe(12);
+          expect(r.error.message).toContain('line 3');
+        }
+      });
+
+      it('hint is non-empty for every error path (charter proposition 3)', async () => {
+        const payload = { message: 'parse failed', line_num: 1, line_pos: 1 };
+        _parse.mockImplementationOnce(() => {
+          throw new Error(JSON.stringify(payload));
+        });
+        const { parse } = await import('../index.js');
+        const r = await parse('invalid');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+          expect(r.error.hint).toBeTruthy();
+          expect(r.error.hint.length).toBeGreaterThan(0);
+        }
+      });
+    });
+  });
+}
+
+{
+  // ─── from validate.test.ts ───
+
+  describe('validate.test.ts', () => {
+    describe('@forgeax/engine-naga validate wrapper', () => {
+      beforeEach(() => {
+        _parse.mockReset();
+        _validate.mockReset();
+        _emit_reflection.mockReset();
+        vi.resetModules();
+      });
+
+      afterEach(() => {
+        vi.clearAllMocks();
+      });
+
+      it('returns Result.ok(opaque handle) when raw wasm validate succeeds', async () => {
+        const parsedHandle = { _tag: 'ParsedModule' };
+        const validatedHandle = { _tag: 'ValidatedModule' };
+        _validate.mockReturnValueOnce(validatedHandle);
+        const { validate } = await import('../index.js');
+        const r = await validate(parsedHandle);
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+          expect(r.value).toBe(validatedHandle);
+        }
+        expect(_validate).toHaveBeenCalledTimes(1);
+        expect(_validate).toHaveBeenCalledWith(parsedHandle);
+      });
+
+      it('returns Result.err(ShaderError) with prose fallback when validator throws non-JSON message', async () => {
+        _validate.mockImplementationOnce(() => {
+          throw new Error('validate failed: type mismatch in @location(0)');
+        });
+        const { validate } = await import('../index.js');
+        const r = await validate({ _tag: 'ParsedModule' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+          expect(r.error.code).toBe('shader-compile-failed');
+          expect(r.error.message).toContain('type mismatch');
+          expect(r.error.lineNum).toBeUndefined();
+          expect(r.error.linePos).toBeUndefined();
+          expect(r.error.hint).toBeTruthy();
+        }
+      });
+    });
+  });
+}