@forgeax/engine-shader 0.1.23 → 0.1.25

package/README.md

@@ -22,6 +22,82 @@ second manifest or registry.
 > Runtime 只查找已发布的 content-addressed artifact；恢复沿 producer、cook
 > 与 catalog 的 owner 边界进行，不在 app 侧复制 shader artifact。
 
+## Standard Surface contract
+
+Standard material 的作者只需要通过 `#import` 使用
+[`surface_v1.wgsl`](./src/surface_v1.wgsl)，并实现唯一的
+`evaluate_surface(SurfaceInput) -> SurfaceData`。`SurfaceData` 是 Standard
+BRDF 的输入，不是最终颜色；Engine-owned Standard pass family 负责顶点、光照、
+阴影、Forward/Deferred、G-buffer、雾和输出。内建默认值位于
+[`default_standard_surface.wgsl`](./src/default_standard_surface.wgsl)。
+
+### Minimal authoring shape
+
+`SurfaceData` is deliberately base-only. Its frozen field order is:
+
+| Order | Field | Meaning |
+|:--:|:--|:--|
+| 1 | `baseColor: vec3<f32>` | Base reflectance color |
+| 2 | `normalWS: vec3<f32>` | World-space shading normal |
+| 3 | `metallic: f32` | Metallic factor |
+| 4 | `roughness: f32` | Roughness factor |
+| 5 | `emissive: vec3<f32>` | Emissive contribution |
+| 6 | `occlusion: f32` | Ambient occlusion factor |
+| 7 | `opacity: f32` | Surface opacity |
+| 8 | `alphaClipThreshold: f32` | Alpha-test threshold |
+
+```wgsl
+#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}
+
+fn evaluate_surface(input: SurfaceInput) -> SurfaceData {
+  return SurfaceData(
+    vec3<f32>(0.45, 0.18, 0.06), input.geometricNormalWS, 0.8, 0.42,
+    vec3<f32>(0.0), 1.0, 1.0, 0.5,
+  );
+}
+```
+
+The matching TypeScript entry is also import-first: the caller names the
+compiled Surface module and supplies only its parameters and values. The
+Engine still owns stage entry points, bindings, BRDF composition, and pass
+projection.
+
+```ts
+import { Materials } from '@forgeax/engine-render';
+
+const rustedIron = Materials.standard({
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  parameters: [
+    { name: 'ironColor', type: 'color' },
+    { name: 'rustDark', type: 'color' },
+    { name: 'rustBright', type: 'color' },
+    { name: 'noiseScale', type: 'f32', default: 1.85 },
+  ],
+  values: {
+    ironColor: [0.4, 0.45, 0.47, 1],
+    rustDark: [0.42, 0.085, 0.018, 1],
+    rustBright: [0.95, 0.34, 0.055, 1],
+    noiseScale: 1.85,
+  },
+});
+```
+
+For the complete source-to-runtime example, see the
+[`game-3d` rusted-iron fixture](../../templates/game-3d/README.md#import-first-surface-material-example).
+
+> [!CAUTION]
+> Surface is a base-facts function only. Do not add `clearcoat`,
+> `clearcoatRoughness`, other physical-layer fields, stage entries, resource
+> bindings, Engine entry points, or vertex-position mutation. Physical layers
+> and pass admission remain Engine-owned.
+
+渐进导航：`Materials.standard()` → `moduleSlots.surface` → build-time
+`#import` composition / reflection → Pack cook → runtime GUID readiness。
+Surface source 不声明 stage entry、`@group/@binding` 或 vertex mutation；参数
+资源由同一 `MaterialAsset.parameters` contract 派生。编译或 cook 失败时读取
+`code`、`detail`、`hint`，修复 authored source 或 producer 后重新 cook，不在
+runtime 读取 raw WGSL 或创建 app-local artifact。
+
 > [!IMPORTANT]
 > A custom material starts as WGSL source plus one `MaterialAsset` contract. The build manifest publishes the composed module and the material cook publishes the resolved record, artifact bytes, references, and receipt. Runtime resolves those facts from the catalog; application code does not install or duplicate shader artifacts. The recovery route is always source or cook repair.
 
@@ -101,10 +177,19 @@ code-specific `detail` and `hint`:
 | `shader-module-not-found` | The published module is absent | Add it to the build source catalog and rebuild |
 | `material-specialization-not-cooked` | No runtime artifact exists for the selection | Run the cook path and publish its record |
 | `material-specialization-stale-generation` | A dependency changed after cooking | Wait for dependencies to settle and re-cook |
+| `material-surface-slot-missing` | Standard pass has no `surface` module slot | Add the slot to the authored pass and re-cook |
+| `material-surface-abi-mismatch` | Surface export does not match `surface_v1` | Repair `evaluate_surface` signature and re-cook |
+| `material-surface-forbidden-interface` | Surface declares a stage, resource, or vertex mutation | Remove the forbidden interface and re-cook |
+| `material-physical-contract-invalid` | A root physical layer is incomplete or unsupported | Repair the root parameter fragment before composing or cooking |
 
 Never hide one of these errors by creating an app-local artifact or changing a
 demo's material shape.
 
+For the canonical error detail and executable recovery fields, use
+[`material/errors.ts`](../types/src/material/errors.ts). The producer recovery
+path is `inspect -> repair authored source -> cold-cook -> verify publication`;
+runtime does not reinterpret a Surface error.
+
 ## Temporal-v1 accessor
 
 `forgeax_scene_temporal` is the single WGSL accessor ABI for the
@@ -159,13 +244,34 @@ state supplies render inspection and recovery evidence.
 ## Built-in PBR contract
 
 The built-in PBR shader has named coordinate records for base color, metallic
-roughness, normal, specular tint, emissive, and occlusion. Each record carries
-offset, scale, rotation, coordinate set, and physical extent metadata. The
-render package projects the records into the UBO; the shader selects the
-declared vertex coordinate input per slot.
+roughness, normal, specular weight/color, emissive, occlusion, transmission,
+and the declared physical texture slots. Each record carries offset, scale,
+rotation, coordinate set, and physical extent metadata. The render package
+projects the records into the UBO; the shader selects the declared vertex
+coordinate input per slot. `specular`/`specularColor` replace the removed
+The former specular-tint vocabulary was removed in one cut; no compatibility alias is supported.
+
+Physical layer declarations are lowered from the Standard root contract. The
+compiler appends only authored physical resources after the engine-owned IBL
+and transmission region, so a base-only root has no physical binding or sample
+and retains its Deferred pass. The five glTF extensions use the same schema and
+the same Forward physical evaluator; runtime never compiles or patches this
+layout.
 
 ## References
 
 - [`@forgeax/engine-types` MaterialAsset](../types/README.md#materialasset-route)
 - [`@forgeax/engine-pack` cook contract](../pack/README.md#materialasset-cook-contract)
 - [`MaterialAsset migration`](https://github.com/ForgeaXGame/forgeax-engine-harness/blob/main/docs/material-asset-migration.md)
+
+## Surface authoring checklist
+
+- [x] Import `forgeax_material::surface_v1` and return the eight-field `SurfaceData`.
+- [x] Read generated material parameters through `forgeax_material::parameters`.
+- [x] Keep vertex, light, BRDF, pass, binding, and output ownership in Engine modules.
+- [x] Let the root parameter contract determine physical layers and pass admission.
+- [ ] Add an engine entry point or resource binding to a Surface module.
+
+The final unchecked item is intentionally forbidden. If an effect needs its own
+entry points or render targets, declare an explicit full-custom material and
+publish its pass/lane provenance instead of disguising it as a Standard Surface.

package/dist/ShaderRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderRegistry.d.ts","sourceRoot":"","sources":["../src/ShaderRegistry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EACV,8BAA8B,EAC9B,aAAa,EACb,gBAAgB,EAChB,+BAA+B,EAChC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,MAAM,IAAI,YAAY,EAE5B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAI9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,CAAC,IAAI,EAAE;QACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACrC,GAAG,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;CACpC;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAG,WAAoB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAED,+EAA+E;AAC/E,MAAM,WAAW,6BAA8B,SAAQ,mBAAmB;IACxE,QAAQ,CAAC,qBAAqB,EAAE,8BAA8B,CAAC;CAChE;AAID,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAkCD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;;gBAcb,IAAI,EAAE,qBAAqB;IAKvC;;;;;;;;;;;;;;;OAeG;IACG,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IA0L9D;;;;;;;;;;OAUG;IACH,OAAO,IAAI,gBAAgB,CAAC,aAAa,CAAC;IAI1C;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;IA2C/D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAsC7E;;;;;;;;;;;;;OAaG;IACH,oBAAoB,CAClB,UAAU,EAAE,MAAM,GACjB,YAAY,CAAC,6BAA6B,EAAE,WAAW,CAAC;IAc3D;;;;OAIG;IACH,yBAAyB,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIrD,uEAAuE;IACvE,0BAA0B,IAAI,+BAA+B;IAI7D;;;;;;;;;;;OAWG;IACH,6BAA6B,IAAI,gBAAgB,CAAC,2BAA2B,CAAC;CAG/E"}
+{"version":3,"file":"ShaderRegistry.d.ts","sourceRoot":"","sources":["../src/ShaderRegistry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EACV,8BAA8B,EAC9B,aAAa,EACb,gBAAgB,EAChB,+BAA+B,EAChC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,MAAM,IAAI,YAAY,EAE5B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAI9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,CAAC,IAAI,EAAE;QACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACrC,GAAG,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;CACpC;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAG,WAAoB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAED,+EAA+E;AAC/E,MAAM,WAAW,6BAA8B,SAAQ,mBAAmB;IACxE,QAAQ,CAAC,qBAAqB,EAAE,8BAA8B,CAAC;CAChE;AAID,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAkCD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;;gBAcb,IAAI,EAAE,qBAAqB;IAKvC;;;;;;;;;;;;;;;OAeG;IACG,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAyK9D;;;;;;;;;;OAUG;IACH,OAAO,IAAI,gBAAgB,CAAC,aAAa,CAAC;IAI1C;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;IA2C/D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAsC7E;;;;;;;;;;;;;OAaG;IACH,oBAAoB,CAClB,UAAU,EAAE,MAAM,GACjB,YAAY,CAAC,6BAA6B,EAAE,WAAW,CAAC;IAc3D;;;;OAIG;IACH,yBAAyB,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIrD,uEAAuE;IACvE,0BAA0B,IAAI,+BAA+B;IAI7D;;;;;;;;;;;OAWG;IACH,6BAA6B,IAAI,gBAAgB,CAAC,2BAA2B,CAAC;CAG/E"}

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { err, manifestMalformed, materialShaderNotFound, ok, type Result, type R
 export { generateLtcTables, hashLtcTable, LTC_SOURCE_PROVENANCE, LTC_TABLE_HASHES, LTC_TABLE_HEIGHT, LTC_TABLE_INPUT_HASHES, LTC_TABLE_WIDTH, LTC_TABLES, } from './ltc/tables.js';
 export { type MaterialArtifactConflictError, type MaterialArtifactInspection, MaterialArtifactRegistry, type MaterialRuntimeArtifact, } from './material/artifact-registry.js';
 export { createStandardPbrArtifactReceipt, isMaterialShaderArtifact, type MaterialShaderArtifact, type MaterialShaderArtifactReceipt, type MaterialShaderResourceSlot, type MaterialShaderVertexInput, } from './material/artifact-types.js';
-export { DEFAULT_MSDF_TEXT_PARAM_SCHEMA, DEFAULT_SPRITE_PARAM_SCHEMA, DEFAULT_STANDARD_PBR_PARAM_SCHEMA, DEFAULT_UNLIT_PARAM_SCHEMA, STANDARD_PBR_ALPHA_CUTOFF_DEFAULT, STANDARD_PBR_ARTIFACT_RECEIPT, STANDARD_PBR_SKIN_ARTIFACT_RECEIPT, } from './material-schemas.js';
+export { DEFAULT_MSDF_TEXT_PARAM_SCHEMA, DEFAULT_SPRITE_PARAM_SCHEMA, DEFAULT_STANDARD_PBR_PARAM_SCHEMA, DEFAULT_UNLIT_PARAM_SCHEMA, STANDARD_BASE_PARAM_SCHEMA, STANDARD_PBR_ALPHA_CUTOFF_DEFAULT, STANDARD_PBR_ARTIFACT_RECEIPT, STANDARD_PBR_SKIN_ARTIFACT_RECEIPT, STANDARD_PHYSICAL_LAYER_PARAM_SCHEMA, STANDARD_PHYSICAL_TEXTURE_FIELDS, STANDARD_PIPELINE_PARAM_SCHEMA, type StandardPhysicalTextureField, standardPhysicalTextureFields, } from './material-schemas.js';
 export { registerDefaultSpriteLit, type SpriteLitCaps, } from './register-default-sprite-lit.js';
 export { registerDefaultStandardPbrSkin } from './register-default-standard-pbr-skin.js';
 export declare const RECT_AREA_LTC_SHADER_MODULE: "forgeax::lighting-rect-area";
@@ -16,13 +16,21 @@ export declare const BUILTIN_MATERIAL_MODULES: {
     readonly unlit: "forgeax_material::unlit";
     readonly sprite: "forgeax_material::sprite";
 };
+/**
+ * The engine-owned Standard Surface selected by a built-in Standard material.
+ * Keep this explicit in the authored pass so the build-time cooker sees the
+ * same slot contract as Materials.standard().
+ */
+export declare const DEFAULT_STANDARD_SURFACE_MODULE: "forgeax_material::default_standard_surface";
 /** Stable build-time module id for the temporal-v1 accessor owner. */
 export declare const SCENE_DATA_TEMPORAL_V1_SHADER_MODULE: "forgeax_scene_temporal";
 /**
  * Material modules whose shader source and parameter contract are owned by
  * the Engine. They live in the runtime ShaderRegistry, so a Pack containing
  * one of these materials carries authored values only and does not require a
- * project material-cook artifact.
+ * project material-cook artifact. A Standard pass with a project Surface slot
+ * is deliberately excluded: its root composition is project-owned and must
+ * arrive with a cooked material publication.
  */
 export declare const ENGINE_MATERIAL_MODULES: readonly ["forgeax::default-standard-pbr", "forgeax::pbr-skin", "forgeax::default-standard-pbr-skin", "forgeax::default-unlit", "forgeax::default-shadow-caster", "forgeax::sprite", "forgeax::sprite-lit", "forgeax::msdf-text", "forgeax_material::standard", "forgeax_material::unlit", "forgeax_material::sprite", "forgeax_material::sprite-lit"];
 /** Names of the zero-binding Standard reflection-probe shader helpers. */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAoC,MAAM,uBAAuB,CAAC;AAG7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EACL,GAAG,EACH,iBAAiB,EACjB,sBAAsB,EACtB,EAAE,EACF,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,wBAAwB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,GACnC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,KAAK,aAAa,GACnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,eAAO,MAAM,2BAA2B,EAAG,6BAAsC,CAAC;AAClF,OAAO,EACL,4BAA4B,EAC5B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EAClC,cAAc,EACd,cAAc,IAAI,aAAa,EAC/B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,IAAI,mBAAmB,EAChD,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,IAAI,oBAAoB,GACnD,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,KAAK,2BAA2B,EAChC,KAAK,6BAA6B,GACnC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX,sEAAsE;AACtE,eAAO,MAAM,oCAAoC,EAAG,wBAAiC,CAAC;AAEtF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,wVAa1B,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,+BAA+B,2DAGjC,CAAC;AAEZ,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAGjF;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AA0BxE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,mBAAmB,GAAG,aAAa,CAOnF;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,UAAO,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAoC,MAAM,uBAAuB,CAAC;AAG7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EACL,GAAG,EACH,iBAAiB,EACjB,sBAAsB,EACtB,EAAE,EACF,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,wBAAwB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,0BAA0B,EAC1B,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,EAClC,oCAAoC,EACpC,gCAAgC,EAChC,8BAA8B,EAC9B,KAAK,4BAA4B,EACjC,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,KAAK,aAAa,GACnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,eAAO,MAAM,2BAA2B,EAAG,6BAAsC,CAAC;AAClF,OAAO,EACL,4BAA4B,EAC5B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EAClC,cAAc,EACd,cAAc,IAAI,aAAa,EAC/B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,IAAI,mBAAmB,EAChD,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,IAAI,oBAAoB,GACnD,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,KAAK,2BAA2B,EAChC,KAAK,6BAA6B,GACnC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAC1C,4CAAqD,CAAC;AAExD,sEAAsE;AACtE,eAAO,MAAM,oCAAoC,EAAG,wBAAiC,CAAC;AAEtF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,wVAa1B,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,+BAA+B,2DAGjC,CAAC;AAEZ,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAWjF;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AA0BxE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,mBAAmB,GAAG,aAAa,CAiBnF;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,UAAO,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.mjs

@@ -1,14 +1,16 @@
-import { ok, err, ParamSchemaProjectionOwner, findUndeclaredSampledTextures } from '@forgeax/engine-types';
-export { MATERIAL_PARAM_TYPES } from '@forgeax/engine-types';
+import { STANDARD_MATERIAL_PARAM_SCHEMA, STANDARD_PHYSICAL_PARAMETER_NAMES, ok, err, ParamSchemaProjectionOwner, findUndeclaredSampledTextures } from '@forgeax/engine-types';
+export { MATERIAL_PARAM_TYPES, STANDARD_PHYSICAL_TEXTURE_FIELDS, standardPhysicalTextureFields } from '@forgeax/engine-types';
 import { ok as ok$1, err as err$1 } from '@forgeax/engine-rhi';
 export { err, ok } from '@forgeax/engine-rhi';
 
+// src/material-schemas.ts
+
 // src/material/artifact-types.ts
 var STANDARD_PBR_TEXTURES = [
   "baseColorTexture",
   "metallicRoughnessTexture",
   "normalTexture",
-  "specularTintTexture",
+  "specularColorTexture",
   "emissiveTexture",
   "occlusionTexture",
   "transmissionTexture",
@@ -28,7 +30,7 @@ var STANDARD_PBR_NUMERIC_FIELDS = [
   "alphaCutoff",
   "clearcoat",
   "clearcoatRoughness",
-  "specularTint",
+  "specularColor",
   "normalScale",
   "transmission",
   "ior",
@@ -91,39 +93,27 @@ function isMaterialShaderArtifact(value) {
   const artifact = value;
   return typeof artifact.material === "string" && typeof artifact.pass === "string" && typeof artifact.wgsl === "string" && typeof artifact.layoutIdentity === "string" && Array.isArray(artifact.bindings) && Array.isArray(artifact.deps) && Array.isArray(artifact.vertexInputs);
 }
-
-// src/material-schemas.ts
 var STANDARD_PBR_ALPHA_CUTOFF_DEFAULT = 0;
-var DEFAULT_STANDARD_PBR_PARAM_SCHEMA = [
-  { name: "baseColor", type: "color", default: [1, 1, 1, 1] },
-  { name: "metallic", type: "f32", default: 0 },
-  { name: "roughness", type: "f32", default: 0.5 },
-  { name: "metallicChannel", type: "f32", default: 2 },
-  { name: "roughnessChannel", type: "f32", default: 1 },
-  { name: "aoChannel", type: "f32", default: 0 },
-  { name: "extraChannel", type: "f32", default: 0 },
-  { name: "emissive", type: "vec3", colorSpace: "srgb", default: [0, 0, 0] },
-  { name: "emissiveIntensity", type: "f32", default: 0 },
-  { name: "occlusionStrength", type: "f32", default: 1 },
-  { name: "alphaCutoff", type: "f32", default: STANDARD_PBR_ALPHA_CUTOFF_DEFAULT },
-  { name: "clearcoat", type: "f32", default: 0 },
-  { name: "clearcoatRoughness", type: "f32", default: 0.5 },
-  { name: "specularTint", type: "vec3", colorSpace: "srgb", default: [1, 1, 1] },
-  { name: "normalScale", type: "f32", default: 1 },
-  { name: "transmission", type: "f32", default: 0 },
-  { name: "ior", type: "f32", default: 1.5 },
-  { name: "thickness", type: "f32", default: 0 },
-  { name: "attenuationColor", type: "vec3", colorSpace: "linear", default: [1, 1, 1] },
-  { name: "attenuationDistance", type: "f32" },
-  { name: "baseColorTexture", type: "texture2d" },
-  { name: "metallicRoughnessTexture", type: "texture2d" },
-  { name: "normalTexture", type: "texture2d" },
-  { name: "specularTintTexture", type: "texture2d" },
-  { name: "emissiveTexture", type: "texture2d" },
-  { name: "occlusionTexture", type: "texture2d" },
-  { name: "transmissionTexture", type: "texture2d" },
-  { name: "thicknessTexture", type: "texture2d" }
-];
+var DEFAULT_STANDARD_PBR_PARAM_SCHEMA = STANDARD_MATERIAL_PARAM_SCHEMA;
+var STANDARD_PHYSICAL_LAYER_PARAM_SCHEMA = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
+  (entry) => STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name)
+);
+var STANDARD_BASE_PARAM_SCHEMA = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
+  (entry) => !STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name) && ![
+    "transmission",
+    "thickness",
+    "attenuationColor",
+    "attenuationDistance",
+    "transmissionTexture",
+    "thicknessTexture"
+  ].includes(entry.name)
+);
+var STANDARD_PIPELINE_PARAM_SCHEMA = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
+  // The canonical Standard UBO keeps every numeric root coordinate,
+  // including the physical-layer tail. Physical map pairs are engine-owned
+  // resources and are injected after the stable user region.
+  (entry) => !(STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name) && entry.type.startsWith("texture"))
+);
 var STANDARD_PBR_ARTIFACT_RECEIPT = createStandardPbrArtifactReceipt();
 var STANDARD_PBR_SKIN_ARTIFACT_RECEIPT = createStandardPbrArtifactReceipt(true);
 var DEFAULT_UNLIT_PARAM_SCHEMA = [
@@ -33116,18 +33106,35 @@ function hashLtcTable(table) {
 function equalBytes(left, right) {
   return left.length === right.length && left.every((value, index) => value === right[index]);
 }
+function equalParamSchema(left, right) {
+  return JSON.stringify(left.metadata?.paramSchema) === JSON.stringify(right.metadata?.paramSchema);
+}
 var MaterialArtifactRegistry = class {
   #artifacts = /* @__PURE__ */ new Map();
   register(artifact) {
     const previous = this.#artifacts.get(artifact.key);
     if (previous !== void 0) {
-      if (equalBytes(previous.bytes, artifact.bytes)) return ok(previous);
+      if (equalBytes(previous.bytes, artifact.bytes)) {
+        if (equalParamSchema(previous, artifact)) return ok(previous);
+        return err({
+          code: "material-artifact-conflict",
+          expected: "one immutable parameter schema per specialization key",
+          hint: "re-cook the conflicting specialization with one canonical parameter schema",
+          detail: {
+            key: artifact.key,
+            dimension: "param-schema",
+            ...previous.digest ? { existingDigest: previous.digest } : {},
+            ...artifact.digest ? { incomingDigest: artifact.digest } : {}
+          }
+        });
+      }
       return err({
         code: "material-artifact-conflict",
         expected: "one immutable artifact byte sequence per specialization key",
         hint: "re-cook the conflicting specialization and publish one artifact digest",
         detail: {
           key: artifact.key,
+          dimension: "bytes",
           ...previous.digest ? { existingDigest: previous.digest } : {},
           ...artifact.digest ? { incomingDigest: artifact.digest } : {}
         }
@@ -33166,7 +33173,7 @@ var RESERVED_ID2 = "forgeax::pbr-skin";
 function registerDefaultStandardPbrSkin(registry, composedWgsl, caps) {
   registry.installMaterialArtifact(RESERVED_ID2, {
     source: composedWgsl,
-    paramSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA
+    paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA
   });
 }
 var FORGEAX_RESERVED_PATH_PREFIX = "forgeax::";
@@ -33343,20 +33350,6 @@ var ShaderRegistry = class {
           }
           variantKeys.add(variant.definesKey);
         }
-        if (ms.identifier === "forgeax::default-standard-pbr") {
-          const transmissionStates = new Set(
-            ms.variants.filter((variant) => "TRANSMISSION_AVAILABLE" in variant.defines).map((variant) => variant.defines.TRANSMISSION_AVAILABLE)
-          );
-          if (!transmissionStates.has(false) || !transmissionStates.has(true)) {
-            return err$1(
-              manifestMalformed({
-                message: "ShaderRegistry: Standard material shader is missing a transmission variant state",
-                hint: "forgeax::default-standard-pbr must declare TRANSMISSION_AVAILABLE=false and true",
-                reason: `declared transmission states: ${JSON.stringify([...transmissionStates])}`
-              })
-            );
-          }
-        }
         validatedMaterialShaderEntries.push(ms);
       }
     }
@@ -33609,6 +33602,7 @@ var BUILTIN_MATERIAL_MODULES = {
   unlit: "forgeax_material::unlit",
   sprite: "forgeax_material::sprite"
 };
+var DEFAULT_STANDARD_SURFACE_MODULE = "forgeax_material::default_standard_surface";
 var SCENE_DATA_TEMPORAL_V1_SHADER_MODULE = "forgeax_scene_temporal";
 var ENGINE_MATERIAL_MODULES = [
   "forgeax::default-standard-pbr",
@@ -33633,7 +33627,9 @@ function isEngineMaterialModule(module) {
 }
 function isEngineMaterial(material) {
   const passes = material.passes ?? [];
-  return passes.length > 0 && passes.every((pass) => isEngineMaterialModule(pass.program.module));
+  return passes.length > 0 && passes.every(
+    (pass) => isEngineMaterialModule(pass.program.module) && (pass.program.moduleSlots?.surface === void 0 || pass.program.moduleSlots.surface === DEFAULT_STANDARD_SURFACE_MODULE)
+  );
 }
 var BUILTIN_PARAMETERS = {
   standard: [
@@ -33658,13 +33654,21 @@ var BUILTIN_VALUES = {
 function createBuiltinMaterialAsset(kind) {
   return {
     kind: "material",
-    passes: [{ name: "forward", program: { module: BUILTIN_MATERIAL_MODULES[kind] } }],
+    passes: [
+      {
+        name: "forward",
+        program: {
+          module: BUILTIN_MATERIAL_MODULES[kind],
+          ...kind === "standard" ? { moduleSlots: { surface: DEFAULT_STANDARD_SURFACE_MODULE } } : {}
+        }
+      }
+    ],
     parameters: BUILTIN_PARAMETERS[kind],
     values: BUILTIN_VALUES[kind]
   };
 }
 var TONEMAP_LUMINANCE_EPSILON = 1e-5;
 
-export { BUILTIN_MATERIAL_MODULES, DEFAULT_MSDF_TEXT_PARAM_SCHEMA, DEFAULT_SPRITE_PARAM_SCHEMA, DEFAULT_STANDARD_PBR_PARAM_SCHEMA, DEFAULT_UNLIT_PARAM_SCHEMA, ENGINE_MATERIAL_MODULES, FORGEAX_RESERVED_PATH_PREFIX, LTC_SOURCE_PROVENANCE, LTC_TABLES, LTC_TABLE_HASHES, LTC_TABLE_HEIGHT, LTC_TABLE_INPUT_HASHES, LTC_TABLE_WIDTH, MaterialArtifactRegistry, RECT_AREA_LTC_SHADER_MODULE, REFLECTION_PROBE_SHADER_HELPERS, SCENE_DATA_TEMPORAL_V1_SHADER_MODULE, STANDARD_PBR_ALPHA_CUTOFF_DEFAULT, STANDARD_PBR_ARTIFACT_RECEIPT, STANDARD_PBR_SKIN_ARTIFACT_RECEIPT, ShaderRegistry as ShaderCatalog, ShaderError, ShaderRegistry, TONEMAP_LUMINANCE_EPSILON, TONEMAP_SHADER_MODE, createBuiltinMaterialAsset, createStandardPbrArtifactReceipt, findVariantByKey, generateLtcTables, hashLtcTable, isEngineMaterial, isEngineMaterialModule, isMaterialShaderArtifact, manifestMalformed, materialShaderNotFound, registerDefaultSpriteLit, registerDefaultStandardPbrSkin, shaderNotFound };
+export { BUILTIN_MATERIAL_MODULES, DEFAULT_MSDF_TEXT_PARAM_SCHEMA, DEFAULT_SPRITE_PARAM_SCHEMA, DEFAULT_STANDARD_PBR_PARAM_SCHEMA, DEFAULT_STANDARD_SURFACE_MODULE, DEFAULT_UNLIT_PARAM_SCHEMA, ENGINE_MATERIAL_MODULES, FORGEAX_RESERVED_PATH_PREFIX, LTC_SOURCE_PROVENANCE, LTC_TABLES, LTC_TABLE_HASHES, LTC_TABLE_HEIGHT, LTC_TABLE_INPUT_HASHES, LTC_TABLE_WIDTH, MaterialArtifactRegistry, RECT_AREA_LTC_SHADER_MODULE, REFLECTION_PROBE_SHADER_HELPERS, SCENE_DATA_TEMPORAL_V1_SHADER_MODULE, STANDARD_BASE_PARAM_SCHEMA, STANDARD_PBR_ALPHA_CUTOFF_DEFAULT, STANDARD_PBR_ARTIFACT_RECEIPT, STANDARD_PBR_SKIN_ARTIFACT_RECEIPT, STANDARD_PHYSICAL_LAYER_PARAM_SCHEMA, STANDARD_PIPELINE_PARAM_SCHEMA, ShaderRegistry as ShaderCatalog, ShaderError, ShaderRegistry, TONEMAP_LUMINANCE_EPSILON, TONEMAP_SHADER_MODE, createBuiltinMaterialAsset, createStandardPbrArtifactReceipt, findVariantByKey, generateLtcTables, hashLtcTable, isEngineMaterial, isEngineMaterialModule, isMaterialShaderArtifact, manifestMalformed, materialShaderNotFound, registerDefaultSpriteLit, registerDefaultStandardPbrSkin, shaderNotFound };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map