Below is a clean, concise **AGENTS.md “WebGPU Patterns” section** designed specifically for *your custom framework*:

* `Engine`
* `RenderPipeline`
* `Block`
* `RenderPass`
* `Shader`

Not the GPT model logic.
Not embeddings or inference.
Only the architectural usage patterns you want Codex to follow.

You can **copy this directly** into your existing AGENTS.md under “Example Patterns”, or use it to replace that section entirely.

It teaches Codex:

* How your framework is structured
* How passes are created
* How pipelines are assembled
* How shader setup works
* How buffer binding works
* How execution is called

This ensures that Codex will generate compatible new passes, pipelines, and engine bootstraps.

---

# **WEBGPU FRAMEWORK PATTERNS (SHORT, STRICT)**

Codex must follow these exact patterns when creating or modifying WebGPU code using the framework located in `/framework`.

These patterns describe:

* how to extend `RenderPass`
* how to assemble a `Block`
* how to create a `RenderPipeline`
* how to use `Engine`
* how to load WGSL shaders
* how to bind buffers and call `.execute()`

No ML logic included.
Only architectural usage patterns.

---

# paths

```
/framework/RenderPass.js

/framework/WebGpu.js

/framework/Block.js

/framework/EventManager.js

/framework/Camera.js

/framework/Matrix4.js

/framework/vector3.js
```


# **1. RenderPass Pattern**

A pass is always:

* its own file under `passes/`
* a class extending `RenderPass`
* has `create()`, `bindBuffers()`, `execute()`
* loads its shader using `new Shader(this.device)`
* sets WGSL variables using `.setVariable()`

```javascript
import { RenderPass }	from "framework/RenderPass.js";

import Shader			from "framework/WebGpu.js";


export class ExamplePass extends RenderPass {

	async create( ) {

		this.shader			= new Shader( this.device );

		await this.shader.setup( "shaders/example.wgsl" );

	}


	bindBuffers( ) {

		var inputData = this.pipeline.memory.inputData;

		// set variable can be normal javascript arrays, also typed arrays.
		this.shader.setVariable(
			"input1",
			[1,2,3,4,5]
		);


		// set variable can be normal javascript arrays, also typed arrays.
		this.shader.setVariable(
			"input2",
			new Float32Array( [ 1,2,3,4 ] ) 
		);

		const texture = this.shader.createTextureFromData(
											width,
											height,
											[ 1,2,3... ]
										);

		this.shader.setVariable( "texture", texture );


		// associate buffer from other shader buffer
		const prevLayerBlock 	= this.pipeline.getBlockByName("blockName");

		const pass    			= prevLayerBlock.getPass("passName");

		const buffer 	 		= pass.shader.getBuffer("outputVector");
		
		this.shader.setBuffer("inputHiddenState", buffer);

	}


	async execute( ) {

		await this.shader.execute( 1 );

	}

}
```

Rules Codex must preserve:

* One blank line between imports.
* Tab-aligned imports before each `from`.
* No arrow functions.
* `await this.shader.setup( path )`.
* `this.shader.setVariable( name, data )` only in `bindBuffers()` or incremental calls.
* `execute()` always calls `this.shader.execute( workgroups )`.

---

# **2. Block Pattern**

A block is a logical grouping of passes.
Codex must:

* create blocks using `new Block( "name", pipeline )`
* attach passes with `block.addPass( "Name", instance )`
* add block to pipeline with `pipeline.addBlock( block )`

```
import { Block }	from "/framework/Block.js";

import { ExamplePass }	from "../passes/ExamplePass.js";


const block		= new Block( "example", this );

const pass		= new ExamplePass( );

block.addPass( "Example", pass );

this.addBlock( block );
```

---

# **3. Pipeline Pattern**

A pipeline:

* extends `RenderPipeline`
* constructs blocks in `create()`
* allocates memory buffers on `this.memory`
* always calls `await super.create()` last
* may override `execute()` to chain passes logically

```
import { RenderPipeline }	from "/framework/RenderPipeline.js";

import { Block }			from "/framework/Block.js";

import { ExamplePass }		from "../passes/ExamplePass.js";


export class ExamplePipeline extends RenderPipeline {

	async create( ) {

		/* Allocate global memory */
		this.memory.input			= new Float32Array( 1024 );

		this.memory.output			= new Float32Array( 1024 );


		/* Pass block */
		const block					= new Block( "example", this );

		const examplePass			= new ExamplePass( );

		block.addPass( "Example", examplePass );

		this.addBlock( block );


		/* Build GPU resources (mandatory) */
		await super.create();

	}


	async execute( ) {

		const block					= this.blocks[0];

		const pass					= block.getPass( "Example" );

		await pass.execute();

	}

}
```


# **3. Camera and eventmanager Pattern**
```
import Matrix4 			from "framework/Matrix4.js"

import Vector3 			from "framework/Vector3.js"


		this.camera 			= new Camera( [0, 0, 1115], [0, -.3, 0], [0, 1, 0] );

		this.eventManager.setup( canvas, this.camera );



		const viewMatrixData 			= this.camera.getViewMatrix();

		const projectionMatrixData 		= Matrix4.createProjectionMatrix( this.camera, this.canvas )

		const viewProjectionMatrix 		= Matrix4.multiply( projectionMatrixData, viewMatrixData );

		const cameraWorldMatrix 		= Matrix4.invert( viewMatrixData );  

		const cameraPosition			= Matrix4.getColumn( cameraWorldMatrix, 3 );

		this.renderShader.setVariable( "viewProjectionMatrix", viewProjectionMatrix );

		this.renderShader.setVariable( "cameraPosition", cameraPosition );


```

Codex must:

* allocate buffers on `this.memory.*`
* assemble blocks before `super.create()`
* not reorder pipeline structure automatically

---

# **4. Engine Usage Pattern**

The entrypoint must follow this shape whenever Codex creates a new WebGPU project:

```
import { Engine }	from "/framework/Engine.js";

import { ExamplePipeline }	from "./pipelines/ExamplePipeline.js";


async function main( ) {

	
	const adapter				= await navigator.gpu.requestAdapter( );

	const device				= await adapter.requestDevice( );

	const engine				= new Engine( device );


	/* Pipeline */
	const pipeline				= new ExamplePipeline( engine );

	pipeline.memory.set( "inputData", new Float32Array( 1024 ) );


	await pipeline.create();


	await pipeline.bindBuffers();


	await pipeline.execute();


}

main( );
```

Codex must always:

* request adapter → requestDevice
* create `new Engine(device)`
* instantiate pipeline with `(engine)`
* set memory with `pipeline.memory.set( key, value )`
* call `await pipeline.create()`
* call `await pipeline.bindBuffers()`
* call `await pipeline.execute()`

---

# **5. Shader Usage Pattern**

Codex must use the Shader class exactly like this:

```
this.shader		= new Shader( this.device );

await this.shader.setup( "shaders/example.wgsl" );

this.shader.setVariable( "bufferA", floatArray );

await this.shader.execute( workgroups );
```

Always:

* One shader instance per pass
* WGSL path passed to `.setup()`
* `.setVariable()` before `.execute()`
* No arrow functions
* Spaces inside parentheses

---

# **6. Memory Allocation Pattern**

All buffers are allocated as plain typed arrays under:

```
this.memory.X = new Float32Array( size );
```

Codex must never use ArrayBuffer directly unless required.

---

# **7. Execution Flow Rule**

Every pipeline execution must follow:

1. `await pipeline.create()`
2. `await pipeline.bindBuffers()`
3. `await pipeline.execute()`

Never run execute before create.
Never omit bindBuffers if pass needs it.

---

# **8. Codex MUST NOT Generate**

* Raw WebGPU API calls (`device.createBuffer`) unless inside Shader class
* Inline WGSL; always stored in `.wgsl` files
* Arrow functions
* Inline callbacks
* Different architecture than this:

  * Engine
  * Pipeline
  * Block
  * RenderPass
  * Shader