@forgeax/engine-shader 0.1.20 → 0.1.23

package/dist/ltc/provenance.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The table source is the Three.js r184 RectAreaLight implementation. The
+ * source arrays are converted to IEEE-754 binary16 offline and checked into
+ * `tables.ts`; the runtime never fetches or parses a source file.
+ */
+export declare const LTC_SOURCE_PROVENANCE: {
+    readonly source: "Three.js";
+    readonly revision: "r184";
+    readonly sourceUrl: "https://github.com/mrdoob/three.js/blob/r184/examples/jsm/lights/RectAreaLightTexturesLib.js";
+    readonly upstreamData: "selfshadow/ltc_code fit/results/ltc.js";
+    readonly generator: "deterministic Three.js source-array to rgba16float conversion";
+    readonly inputSha256: {
+        readonly lambert: "cf5cf21e5c112d2095c7e2418cb0a1ac54636e275d73e42f3453646c67f26814";
+        readonly ggx: "3b1b09080b26104498db277c14fc1733786465c6958e7a8403d688b1e24c2ff5";
+    };
+};
+//# sourceMappingURL=provenance.d.ts.map

package/dist/ltc/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/ltc/provenance.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;CAWxB,CAAC"}

package/dist/ltc/tables.d.ts

@@ -0,0 +1,22 @@
+import { LTC_SOURCE_PROVENANCE } from './provenance';
+export { LTC_SOURCE_PROVENANCE };
+export declare const LTC_TABLE_WIDTH = 64;
+export declare const LTC_TABLE_HEIGHT = 64;
+export declare const LTC_TABLES: {
+    readonly lambert: Uint16Array<ArrayBuffer>;
+    readonly ggx: Uint16Array<ArrayBuffer>;
+};
+export declare const LTC_TABLE_HASHES: {
+    readonly lambert: "a391de32f868fd4aa8774917b793174b7be804c08e2fb8924c30f31d7aa8dcd7";
+    readonly ggx: "fa1ecbc6deb3c85ddf603cdf1e98e30279444f905eb1cebb849d761b570dd696";
+};
+export declare const LTC_TABLE_INPUT_HASHES: {
+    readonly lambert: "cf5cf21e5c112d2095c7e2418cb0a1ac54636e275d73e42f3453646c67f26814";
+    readonly ggx: "3b1b09080b26104498db277c14fc1733786465c6958e7a8403d688b1e24c2ff5";
+};
+export declare function generateLtcTables(): {
+    lambert: Uint16Array;
+    ggx: Uint16Array;
+};
+export declare function hashLtcTable(table: Uint16Array): string;
+//# sourceMappingURL=tables.d.ts.map

package/dist/ltc/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/ltc/tables.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,qBAAqB,EAAE,CAAC;AACjC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAorFnC,eAAO,MAAM,UAAU;;;CAAkD,CAAC;AAC1E,eAAO,MAAM,gBAAgB;;;CAGnB,CAAC;AACX,eAAO,MAAM,sBAAsB;;;CAAoC,CAAC;AAExE,wBAAgB,iBAAiB,IAAI;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,CAAA;CAAE,CAE9E;AAwED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEvD"}

package/dist/material/artifact-types.d.ts

@@ -1,13 +1,65 @@
 import type { BindGroupLayoutDescriptor } from '@forgeax/engine-types';
+export interface MaterialShaderResourceSlot {
+    readonly name: string;
+    readonly parameter: string;
+    readonly kind: 'sampler' | 'texture';
+    readonly group: number;
+    readonly binding: number;
+}
+export interface MaterialShaderVertexInput {
+    readonly semantic: string;
+    readonly location: number;
+    readonly format: string;
+}
+export interface MaterialShaderArtifactReceipt {
+    readonly directEntry: string;
+    readonly sceneIndexEntry: string;
+    readonly materialRow: {
+        readonly byteLength: number;
+        readonly fields: readonly string[];
+    };
+    readonly resourceSlots: readonly MaterialShaderResourceSlot[];
+    readonly uvSets: readonly {
+        readonly parameter: string;
+        readonly set: number;
+    }[];
+    readonly vertexInputs: readonly MaterialShaderVertexInput[];
+    readonly alphaMask: {
+        readonly cutoff: string;
+        readonly source: string;
+    };
+    readonly skinPaletteAddress?: {
+        readonly group: number;
+        readonly binding: number;
+        readonly stride: number;
+    };
+    readonly reflection: {
+        readonly layoutIdentity: string;
+        readonly resourceSlots: readonly MaterialShaderResourceSlot[];
+        readonly vertexInputs: readonly MaterialShaderVertexInput[];
+    };
+    readonly receiptIdentity: string;
+    readonly generation: number;
+}
 export interface MaterialShaderArtifact {
     readonly material: string;
     readonly pass: string;
     readonly wgsl: string;
     readonly layoutIdentity: string;
+    /** Naga-reflected UV set count used to derive clamp-to-last vertex aliases. */
+    readonly uvSetCount?: number;
     readonly bindings: readonly BindGroupLayoutDescriptor[];
     readonly deps: readonly string[];
     readonly vertexInputs: readonly Readonly<Record<string, unknown>>[];
     readonly specializationKey?: string;
+    /** Producer-owned ABI facts shared by direct and scene-index consumers. */
+    readonly receipt?: MaterialShaderArtifactReceipt;
 }
+/**
+ * Builds the one Standard PBR ABI receipt consumed by both material lanes.
+ * The skinned module uses the same material producer and only adds its palette
+ * address; it must retain the same receipt identity for material compatibility.
+ */
+export declare function createStandardPbrArtifactReceipt(skinned?: boolean): MaterialShaderArtifactReceipt;
 export declare function isMaterialShaderArtifact(value: unknown): value is MaterialShaderArtifact;
 //# sourceMappingURL=artifact-types.d.ts.map

package/dist/material/artifact-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-types.d.ts","sourceRoot":"","sources":["../../src/material/artifact-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAYxF"}
+{"version":3,"file":"artifact-types.d.ts","sourceRoot":"","sources":["../../src/material/artifact-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEvE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,QAAQ,CAAC,aAAa,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjF,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC5D,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,aAAa,EAAE,SAAS,0BAA0B,EAAE,CAAC;QAC9D,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;KAC7D,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,6BAA6B,CAAC;CAClD;AA8DD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,UAAQ,GAAG,6BAA6B,CA2B/F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAYxF"}

package/dist/material-schemas.d.ts

@@ -1,7 +1,12 @@
 import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import { type MaterialShaderArtifactReceipt } from './material/artifact-types.js';
 export declare const STANDARD_PBR_ALPHA_CUTOFF_DEFAULT = 0;
 /** Shared material contract for the standard PBR and skinned PBR shaders. */
 export declare const DEFAULT_STANDARD_PBR_PARAM_SCHEMA: readonly ParamSchemaEntry[];
+/** The single producer receipt shared by direct and scene-index Standard PBR. */
+export declare const STANDARD_PBR_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt;
+/** Skinned Standard PBR keeps the material receipt identity and adds palette ABI. */
+export declare const STANDARD_PBR_SKIN_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt;
 export declare const DEFAULT_UNLIT_PARAM_SCHEMA: readonly ParamSchemaEntry[];
 export declare const DEFAULT_SPRITE_PARAM_SCHEMA: readonly ParamSchemaEntry[];
 export declare const DEFAULT_MSDF_TEXT_PARAM_SCHEMA: readonly ParamSchemaEntry[];

package/dist/material-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"material-schemas.d.ts","sourceRoot":"","sources":["../src/material-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,6EAA6E;AAC7E,eAAO,MAAM,iCAAiC,EAAE,SAAS,gBAAgB,EA6BxE,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,SAAS,gBAAgB,EAIjE,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,gBAAgB,EAMlE,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,SAAS,gBAAgB,EAIrE,CAAC"}
+{"version":3,"file":"material-schemas.d.ts","sourceRoot":"","sources":["../src/material-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,8BAA8B,CAAC;AAEtC,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,6EAA6E;AAC7E,eAAO,MAAM,iCAAiC,EAAE,SAAS,gBAAgB,EA6BxE,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,EAAE,6BACR,CAAC;AAErC,qFAAqF;AACrF,eAAO,MAAM,kCAAkC,EAAE,6BACT,CAAC;AAEzC,eAAO,MAAM,0BAA0B,EAAE,SAAS,gBAAgB,EAIjE,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,gBAAgB,EAMlE,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,SAAS,gBAAgB,EAIrE,CAAC"}

package/dist/register-default-sprite-lit.d.ts

@@ -22,12 +22,9 @@ export interface SpriteLitCaps {
  * compiled by @forgeax/engine-vite-plugin-shader at build time and surfaced
  * in manifest.json. The caller reads it from the manifest entries.
  *
- * `caps.storageBuffer` switches the runtime BGL buffer types for
- * @group(0) bindings 1+2 (pointLightsBuffer / spotLightsBuffer):
- * `false` -> uniform fallback (AC-10 WebGL2 path); `true` -> read-only-storage.
- * The BGL itself is built downstream in runtime/pbr-pipeline.ts (sprite-lit
- * reuses pbr-view / pbr-mesh-array / pbr-instances unchanged; AC-07
- * BGL byte-identical).
+ * `caps.storageBuffer` is retained for the shared mesh/instance layout
+ * selection. Sprite-lit local lighting reads the same Standard Cluster group
+ * as PBR; the view group has no direct point/spot arrays.
  *
  * @param registry ShaderRegistry instance (engine boot path).
  * @param composedWgsl Post-naga_oil composed WGSL source string.

package/dist/register-default-sprite-lit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-default-sprite-lit.d.ts","sourceRoot":"","sources":["../src/register-default-sprite-lit.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAiBjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,aAAa,GAClB,IAAI,CAUN"}
+{"version":3,"file":"register-default-sprite-lit.d.ts","sourceRoot":"","sources":["../src/register-default-sprite-lit.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAiBjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,aAAa,GAClB,IAAI,CAUN"}

package/dist/types.d.ts

@@ -11,6 +11,7 @@
  * no longer carry a bindingLayout sidecar (§Change stance: no v1/v2
  * dual-path, no incremental drop window).
  */
+import type { MaterialShaderArtifactReceipt } from './material/artifact-types.js';
 export interface MaterialShaderManifestVariant {
     readonly definesKey: string;
     readonly defines: Record<string, boolean>;
@@ -26,7 +27,7 @@ export interface MaterialShaderManifestVariant {
  *
  * For Engine.create() internal use only; AI users never see this type.
  */
-export interface MaterialShaderManifestEntry {
+export interface MaterialShaderManifestEntry extends Partial<MaterialShaderArtifactReceipt> {
     readonly identifier: string;
     readonly sourcePath: string;
     readonly composedWgsl: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,2BAA2B,EAClC,UAAU,EAAE,MAAM,GACjB,6BAA6B,GAAG,SAAS,CAE3C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAClF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA4B,SAAQ,OAAO,CAAC,6BAA6B,CAAC;IACzF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,2BAA2B,EAClC,UAAU,EAAE,MAAM,GACjB,6BAA6B,GAAG,SAAS,CAE3C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-shader",
-  "version": "0.1.20",
+  "version": "0.1.23",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,12 +22,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-rhi": "0.1.20",
-    "@forgeax/engine-types": "0.1.20",
+    "@forgeax/engine-rhi": "0.1.23",
+    "@forgeax/engine-types": "0.1.23",
     "@webgpu/types": "^0.1.71"
   },
   "devDependencies": {
-    "@forgeax/engine-vite-plugin-shader": "0.1.20"
+    "@forgeax/engine-vite-plugin-shader": "0.1.23"
   },
   "forgeax": {
     "metrics": {

package/src/ShaderRegistry.ts

@@ -122,6 +122,36 @@ export interface ShaderRegistryOptions {
   readonly manifestUrl: string | undefined;
 }
 
+type ShaderManifestDiagnostic = {
+  readonly name: string;
+  readonly startedAt: number;
+  readonly previousElapsedMs: number;
+  readonly url?: string;
+  readonly status?: number;
+  readonly responseUrl?: string;
+  readonly entryCount?: number;
+  readonly materialShaderCount?: number;
+  readonly error?: string;
+};
+
+function markShaderManifestStage(
+  name: string,
+  detail: Omit<ShaderManifestDiagnostic, 'name' | 'startedAt' | 'previousElapsedMs'> = {},
+): void {
+  if (typeof globalThis === 'undefined') return;
+  const host = globalThis as {
+    __forgeaxShaderManifest?: ShaderManifestDiagnostic;
+  };
+  const previous = host.__forgeaxShaderManifest;
+  const now = Date.now();
+  host.__forgeaxShaderManifest = {
+    name,
+    startedAt: now,
+    previousElapsedMs: previous === undefined ? 0 : now - previous.startedAt,
+    ...detail,
+  };
+}
+
 // ─── ShaderRegistry main class (instance-per-engine) ============================
 
 /**
@@ -194,10 +224,35 @@ export class ShaderRegistry {
     }
 
     let raw: string;
+    markShaderManifestStage('shader-manifest-fetch-start', { url: this.#manifestUrl });
     try {
       const response = await fetch(this.#manifestUrl);
+      markShaderManifestStage('shader-manifest-response', {
+        url: this.#manifestUrl,
+        status: response.status,
+        responseUrl: response.url,
+      });
+      if (!response.ok) {
+        markShaderManifestStage('shader-manifest-http-failed', {
+          url: this.#manifestUrl,
+          status: response.status,
+          responseUrl: response.url,
+          error: `HTTP ${response.status} ${response.statusText}`,
+        });
+        return err(
+          manifestMalformed({
+            message: `ShaderRegistry: manifest request returned HTTP ${response.status}`,
+            hint: 'verify the dev manifest middleware or production manifest asset is reachable',
+            reason: `${response.statusText || 'HTTP error'} at ${this.#manifestUrl}`,
+          }),
+        );
+      }
       raw = await response.text();
     } catch (e) {
+      markShaderManifestStage('shader-manifest-fetch-failed', {
+        url: this.#manifestUrl,
+        error: e instanceof Error ? e.message : String(e),
+      });
       return err(
         manifestMalformed({
           message: `ShaderRegistry: failed to fetch manifest at ${this.#manifestUrl}`,
@@ -211,6 +266,10 @@ export class ShaderRegistry {
     try {
       parsed = JSON.parse(raw);
     } catch (e) {
+      markShaderManifestStage('shader-manifest-json-failed', {
+        url: this.#manifestUrl,
+        error: e instanceof Error ? e.message : String(e),
+      });
       return err(
         manifestMalformed({
           message: 'ShaderRegistry: manifest JSON parse failed',
@@ -325,6 +384,12 @@ export class ShaderRegistry {
     this.#materialShaderManifestEntries.length = 0;
     this.#materialShaderManifestEntries.push(...validatedMaterialShaderEntries);
     this.#manifestLoaded = true;
+    markShaderManifestStage('shader-manifest-validated', {
+      url: this.#manifestUrl,
+      status: 200,
+      entryCount: validatedEntries.length,
+      materialShaderCount: validatedMaterialShaderEntries.length,
+    });
     return ok(undefined);
   }
 

package/src/__tests__/bloom-fxaa-tonemap.unit.test.ts

@@ -51,7 +51,10 @@ describe('post shader color-domain contract', () => {
     }
     expect(body).toMatch(/default:\s*\{\s*mapped\s*=\s*sample;\s*\}/);
     expect(body).toContain('let encoded = linearToSrgbOetf(mapped);');
-    expect(body).toContain('return vec4<f32>(encoded, source.a);');
+    expect(body).toContain('let output = select(');
+    expect(body).toContain('ditherUnorm8(encoded, in.position.xy)');
+    expect(body).toContain('params.ditherEnabled > 0.5');
+    expect(body).toContain('return vec4<f32>(output, source.a);');
     expect(body).not.toContain('linearToSrgbOetf(exposed)');
   });
 
@@ -84,13 +87,36 @@ describe('post shader color-domain contract', () => {
     expect(`${tonemap}\n${bloom}\n${fxaa}`).not.toContain('encodedDestinationBlend');
   });
 
-  it('returns display-encoded RGB directly from both FXAA exits', () => {
+  it('returns display-encoded RGB from both FXAA exits through the dither gate', () => {
     const body = functionBody(codeOnly(fxaa), 'fs_main');
-    expect(body).toMatch(/return vec4<f32>\(centerColor, 1\.0\);/);
-    expect(body).toMatch(/return vec4<f32>\(finalColor, 1\.0\);/);
+    expect(fxaa).toContain('struct FxaaParams');
+    expect(fxaa).toMatch(/@group\(0\)\s+@binding\(2\)\s+var<uniform> params/);
+    expect(body).toContain('params.ditherEnabled > 0.5');
+    expect(body).toContain('select(centerColor, ditherUnorm8(centerColor, in.position.xy)');
+    expect(body).toContain('select(finalColor, ditherUnorm8(finalColor, in.position.xy)');
     expect(body).not.toMatch(/linearToSrgbOetf\s*\(/);
   });
 
+  it('dithers the final FXAA output before the 8-bit surface quantization', () => {
+    const code = codeOnly(fxaa);
+    const body = functionBody(code, 'fs_main');
+    expect(common).toContain('fn ditherUnorm8');
+    expect(common).toContain('fn ditherNoise');
+    expect(code).not.toContain('fn ditherUnorm8');
+    expect(code).not.toContain('fn ditherNoise');
+    expect(code).toContain('in.position.xy');
+    expect(body).toContain('ditherUnorm8(centerColor, in.position.xy)');
+    expect(body).toContain('ditherUnorm8(finalColor, in.position.xy)');
+
+    const quantize = (value: number, noise: number): number =>
+      Math.round(Math.min(1, Math.max(0, value + (0.5 - noise) * (1 / 255))) * 255);
+    expect(quantize(0.5, 0)).toBe(128);
+    expect(quantize(0.5, 1)).toBe(127);
+    expect(quantize(0, 0)).toBe(1);
+    expect(quantize(0, 1)).toBe(0);
+    expect(quantize(1, 1)).toBe(255);
+  });
+
   it('retains FXAA luma, edge search, and subpixel contract markers', () => {
     const code = codeOnly(fxaa);
     expect(code).toContain('fn rgb2luma');

package/src/__tests__/default-standard-pbr-alpha.unit.test.ts

@@ -16,4 +16,11 @@ describe('standard PBR MASK alpha contract', () => {
     expect(shader).toContain('alpha <= material.alphaCutoff');
     expect(shader).not.toContain('alpha < material.alphaCutoff');
   });
+
+  it('keeps alpha PBR on the shared Directional factor path', () => {
+    expect(shader).toContain('lighting_directional');
+    expect(shader.match(/evalDirectionalShadowFactor\(/g)).toHaveLength(1);
+    expect(shader).toContain('directionalBase');
+    expect(shader).toContain('directionalClearcoat');
+  });
 });

package/src/__tests__/default-standard-pbr-transmission.unit.test.ts

@@ -19,13 +19,17 @@ function device(): ShaderRegistryDevice {
 }
 
 async function engineManifest(): Promise<EngineShaderManifest> {
-  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-  return buildEngineShaderManifest();
+  engineManifestPromise ??= import('@forgeax/engine-vite-plugin-shader').then(
+    ({ buildEngineShaderManifest }) => buildEngineShaderManifest(),
+  );
+  return engineManifestPromise;
 }
 
+let engineManifestPromise: Promise<EngineShaderManifest> | undefined;
+
 describe('default Standard PBR transmission manifest contract', () => {
   it('publishes both TRANSMISSION_AVAILABLE variants from the cooked producer', {
-    timeout: 20_000,
+    timeout: 60_000,
   }, async () => {
     const manifest = await engineManifest();
     const standard = manifest.materialShaders.find(
@@ -37,38 +41,138 @@ describe('default Standard PBR transmission manifest contract', () => {
     const transmissionVariants = standard.variants.filter(
       (variant) => 'TRANSMISSION_AVAILABLE' in variant.defines,
     );
-    expect(transmissionVariants).toHaveLength(32);
-    expect(new Set(transmissionVariants.map((variant) => variant.definesKey)).size).toBe(32);
-    expect(new Set(transmissionVariants.map((variant) => variant.composedWgsl)).size).toBe(32);
-    for (const storageBufferAvailable of [false, true]) {
-      for (const transmissionAvailable of [false, true]) {
-        for (const projectorAvailable of [false, true]) {
-          const expectedKey = [
-            'CLUSTER_FORWARD_AVAILABLE=false',
-            `PROJECTOR_AVAILABLE=${projectorAvailable}`,
-            `STORAGE_BUFFER_AVAILABLE=${storageBufferAvailable}`,
-            `TRANSMISSION_AVAILABLE=${transmissionAvailable}`,
-            'VERTEX_COLOR_AVAILABLE=false',
-          ].join('+');
-          expect(transmissionVariants).toContainEqual(
-            expect.objectContaining({
-              definesKey: expectedKey,
-              defines: expect.objectContaining({
-                CLUSTER_FORWARD_AVAILABLE: false,
-                PROJECTOR_AVAILABLE: projectorAvailable,
-                STORAGE_BUFFER_AVAILABLE: storageBufferAvailable,
-                TRANSMISSION_AVAILABLE: transmissionAvailable,
-                VERTEX_COLOR_AVAILABLE: false,
-              }),
-            }),
-          );
+    // The producer emits the complete supported Cartesian product. Storage is
+    // required for cluster/probe/extended-lighting variants, and extended
+    // lighting additionally requires the projector texture lane. Keep the
+    // expected keys derived here so adding a new axis cannot silently shrink
+    // the published set.
+    const expectedKeys = new Set<string>();
+    for (const clusterForwardAvailable of [false, true]) {
+      for (const storageBufferAvailable of [false, true]) {
+        for (const vertexColorAvailable of [false, true]) {
+          for (const probeBlendAvailable of [false, true]) {
+            for (const extendedLightingAvailable of [false, true]) {
+              for (const directionalPcssAvailable of [false, true]) {
+                for (const transmissionAvailable of [false, true]) {
+                  for (const projectorAvailable of [false, true]) {
+                    for (const reflectionFallbackAvailable of [false, true]) {
+                      if (
+                        (clusterForwardAvailable && !storageBufferAvailable) ||
+                        (probeBlendAvailable && !storageBufferAvailable) ||
+                        (extendedLightingAvailable &&
+                          (!storageBufferAvailable || !projectorAvailable))
+                      ) {
+                        continue;
+                      }
+                      const expectedKeyEntries = [
+                        `CLUSTER_FORWARD_AVAILABLE=${clusterForwardAvailable}`,
+                        `DIRECTIONAL_PCSS_AVAILABLE=${directionalPcssAvailable}`,
+                        `EXTENDED_LIGHTING_AVAILABLE=${extendedLightingAvailable}`,
+                        `PROBE_BLEND_AVAILABLE=${probeBlendAvailable}`,
+                        `PROJECTOR_AVAILABLE=${projectorAvailable}`,
+                        `REFLECTION_FALLBACK_AVAILABLE=${reflectionFallbackAvailable}`,
+                        `STORAGE_BUFFER_AVAILABLE=${storageBufferAvailable}`,
+                        `TRANSMISSION_AVAILABLE=${transmissionAvailable}`,
+                        `VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`,
+                      ];
+                      expectedKeys.add(
+                        expectedKeyEntries.every((entry) => entry.endsWith('=true'))
+                          ? ''
+                          : expectedKeyEntries.join('+'),
+                      );
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    expect(transmissionVariants).toHaveLength(expectedKeys.size);
+    expect(new Set(transmissionVariants.map((variant) => variant.definesKey))).toEqual(
+      expectedKeys,
+    );
+    expect(
+      transmissionVariants.every(
+        (variant) =>
+          !(
+            variant.defines.CLUSTER_FORWARD_AVAILABLE === true &&
+            variant.defines.STORAGE_BUFFER_AVAILABLE === false
+          ) &&
+          !(
+            variant.defines.PROBE_BLEND_AVAILABLE === true &&
+            variant.defines.STORAGE_BUFFER_AVAILABLE === false
+          ) &&
+          !(
+            variant.defines.EXTENDED_LIGHTING_AVAILABLE === true &&
+            (variant.defines.STORAGE_BUFFER_AVAILABLE === false ||
+              variant.defines.PROJECTOR_AVAILABLE === false)
+          ),
+      ),
+    ).toBe(true);
+    for (const clusterForwardAvailable of [false, true]) {
+      for (const storageBufferAvailable of [false, true]) {
+        if (clusterForwardAvailable && !storageBufferAvailable) continue;
+        for (const vertexColorAvailable of [false, true]) {
+          for (const probeBlendAvailable of [false, true]) {
+            for (const extendedLightingAvailable of [false, true]) {
+              for (const directionalPcssAvailable of [false, true]) {
+                for (const transmissionAvailable of [false, true]) {
+                  for (const projectorAvailable of [false, true]) {
+                    for (const reflectionFallbackAvailable of [false, true]) {
+                      if (
+                        (probeBlendAvailable && !storageBufferAvailable) ||
+                        (extendedLightingAvailable &&
+                          (!storageBufferAvailable || !projectorAvailable))
+                      ) {
+                        continue;
+                      }
+                      const expectedKeyEntries = [
+                        `CLUSTER_FORWARD_AVAILABLE=${clusterForwardAvailable}`,
+                        `DIRECTIONAL_PCSS_AVAILABLE=${directionalPcssAvailable}`,
+                        `EXTENDED_LIGHTING_AVAILABLE=${extendedLightingAvailable}`,
+                        `PROBE_BLEND_AVAILABLE=${probeBlendAvailable}`,
+                        `PROJECTOR_AVAILABLE=${projectorAvailable}`,
+                        `REFLECTION_FALLBACK_AVAILABLE=${reflectionFallbackAvailable}`,
+                        `STORAGE_BUFFER_AVAILABLE=${storageBufferAvailable}`,
+                        `TRANSMISSION_AVAILABLE=${transmissionAvailable}`,
+                        `VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`,
+                      ];
+                      const expectedKey = expectedKeyEntries.every((entry) =>
+                        entry.endsWith('=true'),
+                      )
+                        ? ''
+                        : expectedKeyEntries.join('+');
+                      expect(transmissionVariants).toContainEqual(
+                        expect.objectContaining({
+                          definesKey: expectedKey,
+                          defines: expect.objectContaining({
+                            CLUSTER_FORWARD_AVAILABLE: clusterForwardAvailable,
+                            DIRECTIONAL_PCSS_AVAILABLE: directionalPcssAvailable,
+                            EXTENDED_LIGHTING_AVAILABLE: extendedLightingAvailable,
+                            PROBE_BLEND_AVAILABLE: probeBlendAvailable,
+                            PROJECTOR_AVAILABLE: projectorAvailable,
+                            REFLECTION_FALLBACK_AVAILABLE: reflectionFallbackAvailable,
+                            STORAGE_BUFFER_AVAILABLE: storageBufferAvailable,
+                            TRANSMISSION_AVAILABLE: transmissionAvailable,
+                            VERTEX_COLOR_AVAILABLE: vertexColorAvailable,
+                          }),
+                        }),
+                      );
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     }
   });
 
   it('omits transmission-only texture bindings from the fallback variant', {
-    timeout: 20_000,
+    timeout: 60_000,
   }, async () => {
     const manifest = await engineManifest();
     const standard = manifest.materialShaders.find(
@@ -81,6 +185,8 @@ describe('default Standard PBR transmission manifest contract', () => {
       (variant) =>
         variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
+        variant.defines.EXTENDED_LIGHTING_AVAILABLE === false &&
+        variant.defines.PROBE_BLEND_AVAILABLE === false &&
         variant.defines.TRANSMISSION_AVAILABLE === false &&
         variant.defines.VERTEX_COLOR_AVAILABLE === false,
     );
@@ -88,6 +194,8 @@ describe('default Standard PBR transmission manifest contract', () => {
       (variant) =>
         variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
+        variant.defines.EXTENDED_LIGHTING_AVAILABLE === false &&
+        variant.defines.PROBE_BLEND_AVAILABLE === false &&
         variant.defines.TRANSMISSION_AVAILABLE === true &&
         variant.defines.VERTEX_COLOR_AVAILABLE === false,
     );
@@ -98,7 +206,7 @@ describe('default Standard PBR transmission manifest contract', () => {
   });
 
   it('registers one Standard row and resolves a declared variant by exact key', {
-    timeout: 20_000,
+    timeout: 60_000,
   }, async () => {
     const manifest = await engineManifest();
     const standard = manifest.materialShaders.find(

package/src/__tests__/direct-light-layout.unit.test.ts

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+
+async function readShader(name: string): Promise<string> {
+  return readFile(new URL(`../${name}`, import.meta.url), 'utf8');
+}
+
+describe('DirectLightSlot WGSL ABI', () => {
+  it('declares the canonical five-row 80-byte slot', async () => {
+    const common = await readShader('common.wgsl');
+    const match = common.match(/struct DirectLightSlot\s*\{([\s\S]*?)\};/);
+
+    expect(match).not.toBeNull();
+    const struct = match?.[1] ?? '';
+    expect(struct.match(/vec4<f32>/g)).toHaveLength(4);
+    expect(struct.match(/vec4<u32>/g)).toHaveLength(1);
+    expect(struct).toContain('row0');
+    expect(struct).toContain('row1');
+    expect(struct).toContain('row2');
+    expect(struct).toContain('row3');
+    expect(struct).toContain('metadata : vec4<u32>');
+    expect(common).not.toContain('struct DirectLightArray');
+    expect(common).not.toContain('array<DirectLightSlot, 4>');
+    expect(common).toContain('@group(0) @binding(0)');
+  });
+
+  it('keeps the slot type owned by the unified Cluster shader consumer', async () => {
+    const common = await readShader('common.wgsl');
+    const standard = await readShader('default-standard-pbr.wgsl');
+    const clustered = await readShader('standard-cluster.wgsl');
+
+    expect(common).toContain('struct DirectLightSlot');
+    expect(standard).not.toContain('DirectLightSlot');
+    expect(standard).not.toContain('pointLightsBuffer');
+    expect(standard).not.toContain('spotLightsBuffer');
+    expect(clustered).toContain('DirectLightSlot');
+    expect(clustered).toContain('array<DirectLightSlot, 256>');
+    expect(clustered).not.toContain('struct LightSlot');
+  });
+});