ogpu AGENTS.md

AGENTS.md

This file provides guidance to coding agents (Claude Code, OpenAI Codex, Cursor, Gemini CLI, …) when working with code in this repository. It is the shared source of truth. Codex and Cursor Agent mode read it natively; the other tools bridge to it so nothing is duplicated:

• CLAUDE.md — one-line @AGENTS.md import (Claude Code).
• GEMINI.md — one-line @AGENTS.md import (Gemini CLI).
• .cursor/rules/main.mdc — always-applied rule referencing @AGENTS.md (Cursor Chat/Composer).

Commands

Standard scripts (dev, build, preview, lint, format) are in package.json. The one worth documenting:

• npm run validate:shaders — validate every **/*.wgsl in the repo (src/ and examples/ both) with naga (the wgpu WGSL compiler). Install via brew install naga-cli (or cargo install naga-cli) — not brew install naga, which is an unrelated Snake game that conflicts on the same binary name; script exits 2 if absent. Use this to check shader edits without a browser. Single file: node scripts/validate-shaders.mjs <file>.

No tests or typechecker configured. ESLint + Prettier are set up (format-on-save in the repo). No TypeScript, though hand-written ambient declarations live in types/ogpu.d.ts for anyone consuming/migrating to TS.

Coding conventions

• Labels are kebab-case. Every label: string (WebGPU resource debug labels and GUI/tweakpane display text) is lowercase, hyphen-separated; interpolations preserved, e.g. `${this.label}-bone-buffer`.
• WGSL let vs var. In generated shaders use let for values that never change and var only where the binding is reassigned — don't default everything to var.
• WGSL short type aliases. Use the short alias form, not the verbose generic: vec3f not vec3<f32>, vec2u/vec4i not vec2<u32>/vec4<i32>, mat4x4f not mat4x4<f32> (and the h suffix for f16). Texture/atomic/array/ptr types keep their generic form — they have no alias.
• WGSL vertex entry parameter is named in. The vertex stage takes its input struct as in, not v — fn vs(in: Vertex) -> VertexOutput (mirrors fn fs(in: VertexOutput)). Reference attributes as in.position, in.uv, etc.
• Comments are short, terse, and earn their place. Write one only when it adds signal the code can't (a why, a gotcha, a non-obvious invariant); skip narration. Don't restate what belongs in a CLAUDE.md.
• No ponytail: (or other agent-mode) prefixes in committed comments. Keep the comment's content if it earns its place per the rule above — just strip the ponytail:/agent prefix. Generated code carries no trace of the tool that wrote it.
• WebGPU / webgpu-utils → use the lookup skills. Any question or change touching the WebGPU platform uses webgpu-spec-lookup; anything touching the webgpu-utils library uses webgpu-utils-lookup. Don't answer from memory.