@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-create/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: pixijs-create
+description: "Use this skill when scaffolding a new PixiJS v8 project with the create-pixi CLI or adding PixiJS to an existing project. Covers npm/yarn/pnpm/bun create commands, interactive vs non-interactive flows, bundler vs creation template categories, available template presets (bundler-vite, bundler-webpack, bundler-esbuild, bundler-import-map, creation-web, framework-react, extension-default), Node version requirements, `npm install pixi.js` for existing projects, TypeScript 5/6/7 tsconfig setup (moduleResolution, @webgpu/types, @types/web), post-scaffold dev flow, and the Vite top-level-await production-build gotcha. Triggers on: create pixi.js, npm create, npm install pixi.js, scaffold, template, bundler-vite, bundler-webpack, creation-web, framework-react, new project, existing project, getting started, quick start, TypeScript, tsconfig, moduleResolution, @webgpu/types, @types/web, Cannot find name GPUTextureUsage."
+license: MIT
+---
+
+`create pixi.js` is the official CLI for scaffolding a new PixiJS v8 project. Run it with any package manager (`npm`, `yarn`, `pnpm`, `bun`) and pick a template from the interactive menu, or pass `--template` to skip prompts. It writes a self-contained project folder; you then `cd` in, install dependencies, and run the dev script.
+
+## Quick Start
+
+Scaffold a new project with interactive prompts:
+
+```bash
+npm create pixi.js@latest
+```
+
+Or skip prompts by passing a project name and template:
+
+```bash
+npm create pixi.js@latest my-game -- --template bundler-vite
+```
+
+Then:
+
+```bash
+cd my-game
+npm install
+npm run dev
+```
+
+Requires Node.js 18+ or 20+. Some templates (notably `creation-web` and `framework-react`) may require a newer Node version; the package manager will warn if so.
+
+### Adding PixiJS to an existing project
+
+If you already have a bundler, framework, or project set up, skip the CLI and install the package directly:
+
+```bash
+npm install pixi.js
+```
+
+Then import from `pixi.js` and construct an `Application` as shown in `pixijs-application`. The CLI templates are a convenience for new projects; they don't add anything to the library that `npm install pixi.js` can't give you.
+
+**Related skills:** `pixijs-application` (how the scaffolded `new Application()` + `app.init()` entry point works), `pixijs-core-concepts` (renderers and the render loop), `pixijs-scene-core-concepts` (scene graph fundamentals for the first things you'll add to the stage), `pixijs-assets` (loading textures, fonts, and bundles the template expects you to drop into `public/` or `src/assets/`).
+
+## Core Patterns
+
+### Choose a package manager
+
+The command is the same shape for every package manager:
+
+```bash
+npm create pixi.js@latest
+yarn create pixi.js
+pnpm create pixi.js
+bun create pixi.js
+```
+
+Under npm 7+ you must pass a `--` before CLI flags so npm doesn't consume them:
+
+```bash
+npm create pixi.js@latest my-game -- --template bundler-vite
+```
+
+Yarn, pnpm, and bun don't need the extra separator:
+
+```bash
+yarn create pixi.js my-game --template bundler-vite
+pnpm create pixi.js my-game --template bundler-vite
+bun create pixi.js my-game --template bundler-vite
+```
+
+Use `.` as the project name to scaffold into the current directory.
+
+### Interactive flow
+
+Running with no arguments walks through prompts:
+
+1. Project name (defaults to `pixi-project`).
+2. Framework / template category.
+3. Variant (TypeScript vs JavaScript where applicable).
+4. Whether to install dependencies immediately (some runners).
+
+At the end, the CLI prints the `cd` + install + dev commands for the manager you invoked it with.
+
+### Non-interactive flow
+
+Pass a project name and `--template` to skip all prompts. This is the form you want for scripts, CI, and quickstart docs:
+
+```bash
+npm create pixi.js@latest my-game -- --template bundler-vite
+```
+
+### Available template presets
+
+Templates fall into two categories:
+
+- **Bundler templates** (`bundler-*`): generic PixiJS setup wired up with your bundler of choice. Use one of these when you want to pick your own structure.
+- **Creation templates** (`creation-*`): platform-tailored starters with extras already wired in (AssetPack, sound, UI, scene routing). Use one of these when you want batteries included.
+- **Framework templates** (`framework-*`): PixiJS embedded inside a host framework like React.
+- **Extension templates** (`extension-*`): scaffolding for building a reusable PixiJS package.
+
+For most new projects, `bundler-vite` is the recommended starting point.
+
+| Template             | What you get                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `bundler-vite`       | Vite + TypeScript PixiJS project. The default first-stop template.                                           |
+| `bundler-vite-js`    | Vite + plain JavaScript.                                                                                     |
+| `bundler-webpack`    | Webpack + TypeScript.                                                                                        |
+| `bundler-webpack-js` | Webpack + plain JavaScript.                                                                                  |
+| `bundler-esbuild`    | esbuild + TypeScript.                                                                                        |
+| `bundler-esbuild-js` | esbuild + plain JavaScript.                                                                                  |
+| `bundler-import-map` | No-bundler setup using a browser import map (good for learning / demos).                                     |
+| `creation-web`       | PixiJS Creation Engine web template with scene-based game scaffolding, AssetPack, sound, and UI integration. |
+| `framework-react`    | React + TypeScript + PixiJS via the `@pixi/react` package.                                                   |
+| `framework-react-js` | React + plain JavaScript + PixiJS.                                                                           |
+| `extension-default`  | Starter for building a reusable PixiJS extension/package.                                                    |
+
+The live list is maintained in the `create-pixi` repo; run `npm create pixi.js@latest` without arguments to see the current menu if you need to confirm.
+
+### Post-scaffold flow
+
+Every template ships with the same three-step onboarding:
+
+```bash
+cd my-game
+npm install
+npm run dev
+```
+
+`npm run dev` starts the local dev server on the default port (Vite 5173, webpack 8080, etc.; the template's README has the exact number). Changes to `src/` hot-reload without reloading the whole page.
+
+Other scripts every template exposes (names may vary slightly by preset):
+
+- `npm run build`: produce a production build in `dist/`.
+- `npm run preview` / `npm run serve`: serve the production build locally.
+- `npm run lint`: run the template's configured linter if it ships one.
+
+### Scaffolding into an existing directory
+
+Use `.` as the project name to write into the current working directory. The CLI refuses to run if non-empty and conflicting files exist unless you confirm the prompt.
+
+```bash
+mkdir my-game
+cd my-game
+npm create pixi.js@latest . -- --template bundler-vite
+```
+
+### TypeScript setup
+
+PixiJS supports WebGPU, so its type declarations depend on the WebGPU types. Where those come from depends on your TypeScript version.
+
+- **TypeScript 5:** no WebGPU types are built in, so PixiJS adds `@webgpu/types` for you. No additional setup required.
+- **TypeScript 6 and 7:** the WebGPU types are built into the `"dom"` library, but some releases leave parts out, such as `GPUTextureUsage`. Use `@types/web`, which has the full set, in place of `"dom"`. Remove `@webgpu/types` from `types` if it's there, since it conflicts with the built-in types.
+
+```bash
+npm install --save-dev @types/web
+```
+
+```json
+{
+  "compilerOptions": {
+    "lib": ["esnext"],
+    "types": ["@types/web"]
+  }
+}
+```
+
+## Next steps
+
+After `npm run dev` starts, the template opens on a blank or bunny-sprite scene. The usual progression is:
+
+1. Read `pixijs-application` to understand how the template's entry point constructs `new Application()` and calls `await app.init(...)`, how `app.stage` / `app.renderer` / `app.canvas` hang together, and how the ResizePlugin and TickerPlugin behave by default.
+2. Read `pixijs-core-concepts` for the renderer and render-loop mental model.
+3. Read `pixijs-scene-core-concepts` before adding your first non-trivial scene so you know the container-vs-leaf rule upfront.
+4. Drop in textures via `pixijs-assets` once you're ready to load real art.
+
+## Common Mistakes
+
+### [HIGH] Missing `--` separator on npm 7+
+
+Wrong:
+
+```bash
+npm create pixi.js@latest my-game --template bundler-vite
+```
+
+Correct:
+
+```bash
+npm create pixi.js@latest my-game -- --template bundler-vite
+```
+
+npm 7+ consumes flags after the package spec unless you pass `--` to forward them. Without the separator, the CLI ignores `--template` and drops back to the interactive prompt. Yarn, pnpm, and bun don't need the separator.
+
+
+### [MEDIUM] Running with an old Node version
+
+PixiJS requires Node 18+ or 20+. Some templates (framework-react, creation-web) expect a newer Node for their tooling. Upgrade Node before re-running the CLI if you see an "engines" warning from your package manager.
+
+
+### [MEDIUM] Top-level `await app.init()` broken in Vite production builds
+
+On Vite versions `<=6.0.6`, top-level `await` works in dev but breaks in production builds, so a `bundler-vite` project that does this at module scope will fail after `npm run build`:
+
+```ts
+const app = new Application();
+await app.init({ resizeTo: window }); // broken at module top level in prod
+```
+
+Wrap the init in an async IIFE instead:
+
+```ts
+(async () => {
+  const app = new Application();
+  await app.init({ resizeTo: window });
+  document.body.appendChild(app.canvas);
+})();
+```
+
+Upgrading Vite past 6.0.6 also resolves it, but the IIFE pattern is safe on every version and matches the PixiJS quick-start guide.
+
+
+### [HIGH] Keeping `@webgpu/types` in `types` on TypeScript 6 or 7
+
+Wrong:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@webgpu/types"]
+  }
+}
+```
+
+Correct: remove the `"@webgpu/types"` entry and keep any others.
+
+TypeScript 6 and 7 declare the WebGPU types in their built-in `"dom"` library, so `@webgpu/types` declares them a second time. With `skipLibCheck: false` that produces dozens of conflicting-declaration errors inside `lib.dom.d.ts` and `@webgpu/types`. Keep it on TypeScript 5 only, where PixiJS loads it for you anyway.
+
+
+### [MEDIUM] `Cannot find name 'GPUTextureUsage'` on TypeScript 6 or 7
+
+Up to TypeScript 6.0.3 and 7.0.2, the built-in `"dom"` library has no WebGPU flag constants (`GPUBufferUsage`, `GPUColorWrite`, `GPUMapMode`, `GPUShaderStage`, `GPUTextureUsage`), so raw WebGPU code that uses them fails with `TS2552`. Adding `@webgpu/types` back only compiles with `skipLibCheck: true`, because it conflicts with the built-in types. Install `@types/web` 0.0.352 or later, drop `"dom"` from `lib`, and add `"@types/web"` to `types` alongside any existing entries, as shown in [TypeScript setup](#typescript-setup).
+
+
+### [MEDIUM] `moduleResolution: "node"` breaks subpath imports
+
+Wrong:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node"
+  }
+}
+```
+
+Correct:
+
+```json
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+`"node"` (also called `"node10"`) ignores the `exports` field in the PixiJS `package.json`, so `import 'pixi.js/advanced-blend-modes'` and other subpath imports don't resolve. TypeScript 6 reports `TS2882` for them and deprecates the setting (`TS5107`); TypeScript 7 removes it (`TS5108`). Use `"bundler"` if you use a bundler, or `"nodenext"` otherwise.
+
+
+## API Reference
+
+- [create-pixi on GitHub](https://github.com/pixijs/create-pixi)
+- [create-pixi documentation site](https://pixijs.io/create-pixi/)
+- [Application](https://pixijs.download/release/docs/app.Application.html.md): the class the generated entry point instantiates.
+- [TypeScript guide](https://pixijs.download/release/docs/core-concepts-8.html.md): setup for TypeScript 5, 6, and 7.

package/vendor/pixijs-skills/skills/pixijs-custom-rendering/SKILL.md

@@ -0,0 +1,405 @@
+---
+name: pixijs-custom-rendering
+description: "Use this skill when writing custom shaders, uniforms, filters, batchers, or low-level draw code in PixiJS v8. Covers Shader.from({gl, gpu, resources}), GlProgram/GpuProgram, UniformGroup with typed uniforms (f32, vec2, mat4x4), UBO mode, textures as resources, TextureView for depth sampling, 3D and array textures (depth, arrayLayerCount, sampler3D, texture_3d), WebGPU storage textures (storage: true), WGSL override constants, custom bind group layouts (gpuLayout), partial buffer updates (Buffer.update), Geometry.vertexCount/indexCount, TexturePool scratch textures, State winding and culling (clockwiseFrontFace, cullMode), WebGPU render bundles, custom Filter via Filter.from, GLSL ES 3.0 conventions (finalColor), uBackTexture sampling, pixi.js/unsafe-eval for strict CSP, custom Batcher and InstructionPipe.destroyInstructionSet via extensions. Triggers on: Shader, GLSL, WGSL, uniform, custom shader, blendRequired, ShaderOverrides, bind group layout, depth texture, 3D texture, sampler3D, texture_3d, storage texture, getSize, indexCount, TexturePool, getOptimalTexture, destroyInstructionSet, beginBundle, executeBundle, RenderBundle."
+license: MIT
+---
+
+Custom shaders bind GLSL and WGSL programs to scene objects via `Shader.from({ gl, gpu, resources })`. Uniforms live in typed `UniformGroup`s, textures are passed as separate resources, and the same shader can target both WebGL and WebGPU.
+
+## Quick Start
+
+```ts
+const uniforms = new UniformGroup({
+  uTime: { value: 0, type: "f32" },
+});
+
+const shader = Shader.from({
+  gl: { vertex: vertexSrc, fragment: fragmentSrc },
+  resources: { uniforms },
+});
+
+const geometry = new MeshGeometry({
+  positions: new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]),
+  uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
+  indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+});
+
+const mesh = new Mesh({ geometry, shader });
+app.stage.addChild(mesh);
+
+app.ticker.add(() => {
+  shader.resources.uniforms.uniforms.uTime = performance.now() / 1000;
+});
+```
+
+**Related skills:** `pixijs-filters` (built-in filters), `pixijs-scene-mesh` (custom geometry), `pixijs-performance` (batch optimization), `pixijs-migration-v8` (shader API migration from v7).
+
+## Core Patterns
+
+### Dual-renderer shader (WebGL + WebGPU)
+
+```ts
+import { Shader, GlProgram, GpuProgram, UniformGroup } from "pixi.js";
+
+const glVertex = `...`; // GLSL vertex (write `#version 300 es` yourself if you want WebGL2/GLSL ES 3.0)
+const glFragment = `...`; // GLSL fragment
+const wgslSource = `...`; // WGSL combined
+
+const shader = Shader.from({
+  gl: { vertex: glVertex, fragment: glFragment },
+  gpu: {
+    // entryPoint names are arbitrary; they must match the @vertex / @fragment
+    // function names in your WGSL source. PixiJS ships examples using
+    // 'mainVert' / 'mainFrag' but `main` is equally valid.
+    vertex: { entryPoint: "mainVert", source: wgslSource },
+    fragment: { entryPoint: "mainFrag", source: wgslSource },
+  },
+  resources: {
+    myUniforms: new UniformGroup({
+      uColor: { value: new Float32Array([1, 0, 0, 1]), type: "vec4<f32>" },
+      uMatrix: { value: new Float32Array(16), type: "mat4x4<f32>" },
+    }),
+  },
+});
+```
+
+If only `gl` is provided, the shader works with WebGL only. If only `gpu` is provided, it works with WebGPU only. The `compatibleRenderers` bitmask is set automatically.
+
+`GlProgram` does **not** auto-inject `#version 300 es`. If you write `#version 300 es` yourself, PixiJS preserves it and treats the shader as GLSL ES 3.0; otherwise it injects WebGL1 compat macros (`#define in varying`, `#define texture texture2D`) and runs the shader as WebGL1-style GLSL. `GlProgram` always injects a default precision (`highp` vertex, `mediump` fragment) and the program name. It also declares `highp` for sampler types GLSL ES 3.0 gives no default (`usampler2D`, `isampler2D`, `sampler2DArray`, `sampler3D`, and others), so you don't need a precision line for them; one you write yourself is kept. `sampler2D` and `samplerCube` keep their `lowp` default. For GLSL ES 3.0, use `in`/`out` instead of `attribute`/`varying`, `texture()` instead of `texture2D()`, and an `out vec4` instead of `gl_FragColor`.
+
+### Textures as resources
+
+Textures are resources, not uniforms. Pass the texture's `source` and `style` separately:
+
+```ts
+import { Shader, UniformGroup, Texture, Assets } from "pixi.js";
+
+const texture = await Assets.load("myImage.png");
+
+const shader = Shader.from({
+  gl: { vertex: vertSrc, fragment: fragSrc },
+  resources: {
+    uTexture: texture.source,
+    uSampler: texture.source.style,
+    myUniforms: new UniformGroup({
+      uAlpha: { value: 1.0, type: "f32" },
+    }),
+  },
+});
+
+// Swap texture at runtime
+shader.resources.uTexture = otherTexture.source;
+```
+
+Resources are a flat key-value map. The key must match the uniform/binding name in the shader source.
+
+Resources can also be plain objects (auto-wrapped into `UniformGroup`):
+
+```ts
+const shader = Shader.from({
+  gl: { vertex: vertSrc, fragment: fragSrc },
+  resources: {
+    myUniforms: {
+      uTime: { value: 0, type: "f32" },
+    },
+  },
+});
+```
+
+### UBO mode (Uniform Buffer Objects)
+
+UBO mode packs uniforms into a single GPU buffer. Required for WebGPU; optional (WebGL2+) for WebGL.
+
+```ts
+import { UniformGroup } from "pixi.js";
+
+const ubo = new UniformGroup(
+  {
+    uProjection: { value: new Float32Array(16), type: "mat4x4<f32>" },
+    uAlpha: { value: 1.0, type: "f32" },
+  },
+  { ubo: true, isStatic: true },
+);
+
+// Must call update() manually when isStatic is true
+ubo.uniforms.uAlpha = 0.5;
+ubo.update();
+```
+
+UBO rules:
+
+- Only `f32` and `i32` based types are supported (no `u32`). Matrices are float-only.
+- Samplers/textures cannot go in a UBO.
+- The UniformGroup name in resources must exactly match the UBO block name in the shader.
+- Structure and order must exactly match the shader layout.
+- UBO sync uses `new Function` under the hood. In strict-CSP environments (no `unsafe-eval`), import `pixi.js/unsafe-eval` once at startup to swap in the fallback sync path; without it, UBO-backed shaders (and therefore WebGPU) will throw on first use.
+
+### Custom filter
+
+`Filter.from({ gl, resources })` is the shorthand. Pass only a fragment shader; PixiJS supplies a default vertex shader that handles output frame positioning.
+
+```ts
+import { Filter } from "pixi.js";
+
+const filter = Filter.from({
+  gl: {
+    fragment: `
+            in vec2 vTextureCoord;
+            out vec4 finalColor;
+            uniform sampler2D uTexture;
+            uniform float uStrength;
+
+            void main(void) {
+                vec4 color = texture(uTexture, vTextureCoord);
+                finalColor = mix(color, vec4(1.0 - color.rgb, color.a), uStrength);
+            }
+        `,
+  },
+  resources: {
+    filterUniforms: {
+      uStrength: { value: 0.5, type: "f32" },
+    },
+  },
+});
+
+filter.resources.filterUniforms.uniforms.uStrength = 1.0;
+```
+
+For a custom vertex shader, use `new Filter({ glProgram: new GlProgram({ vertex, fragment }), resources })`.
+
+#### Filter shader conventions (GLSL ES 3.0)
+
+- `in vec2 vTextureCoord;` instead of `varying vec2 vTextureCoord;`
+- `out vec4 finalColor;` instead of `gl_FragColor`
+- `texture(uTexture, uv)` instead of `texture2D(uTexture, uv)`
+- The default vertex shader exposes `uInputSize`, `uOutputFrame`, `uOutputTexture` and helpers `filterVertexPosition()` / `filterTextureCoord()`
+
+#### Sampling the render target behind the filter
+
+Set `blendRequired: true` and sample `uBackTexture` in the fragment shader. PixiJS copies the destination pixels into that uniform before running the filter:
+
+```ts
+const blendFilter = Filter.from({
+  gl: { fragment: blendFragSrc },
+  resources: { uniforms: { uAmount: { value: 0.5, type: "f32" } } },
+  blendRequired: true,
+});
+```
+
+Only enable `blendRequired` when you need it; it forces an extra GPU copy every frame.
+
+### Updating uniforms at runtime
+
+```ts
+// Access the UniformGroup via resources
+shader.resources.myUniforms.uniforms.uTime = performance.now() / 1000;
+
+// For isStatic UBOs, call update() after changing values
+shader.resources.myUniforms.update();
+```
+
+### Advanced GPU features
+
+See [references/advanced-gpu.md](references/advanced-gpu.md) for full samples of:
+
+- **Partial buffer and texture uploads**: `buffer.update(sizeInBytes, offsetInBytes)` uploads only the changed byte range; `bufferImageSource.update(startTexel, endTexel)` uploads only a texel range of a data texture.
+- **Vertex and index counts, winding, culling**: `geometry.vertexCount` (replaces the deprecated `getSize()`), `geometry.indexCount` to draw a prefix of a shared index buffer, `state.clockwiseFrontFace` and `cullMode`.
+- **WGSL override constants** (WebGPU): `Shader.from({ gpu, resources, overrides: { STEPS: 8 } })`; each distinct set compiles its own pipeline.
+- **Custom bind group layouts** (WebGPU): generate the default with `generateGpuLayoutGroups(extractStructAndGroups(source))`, edit it, pass it as `gpuLayout`.
+- **Depth sampling with `TextureView`** (WebGPU): bind `new TextureView(depth, { aspect: "depth-only" })` as a resource while the target's depth attachment is `depthReadOnly`.
+- **Integer textures**: `BufferImageSource` with `rgba32uint` etc., `usampler2D`/`texelFetch` and `texture_2d<u32>`/`textureLoad`, `scaleMode: "nearest"`.
+- **3D and array textures**: `depth` or `arrayLayerCount` on a `TextureSource`/`BufferImageSource`, sampled with `sampler3D`/`texture_3d<f32>` or `sampler2DArray`/`texture_2d_array<f32>`; they upload whole, and `renderer.render({ container, target: source, layer })` draws into one slice or layer.
+- **Storage textures** (WebGPU): `storage: true` on a `TextureSource`, then `renderer.texture.getGpuSource(source).createView()` to write it from your own compute pass.
+- **Render bundles** (WebGPU): record draws once with `encoder.beginBundle()` / `endBundle()` and replay with `executeBundle()` while `isBundleValid()` holds.
+- **Pooled scratch textures**: `TexturePool.getOptimalTexture({ width, height, resolution, antialias })` and `returnTexture()`.
+
+### Uniform type reference
+
+See [references/uniform-types.md](references/uniform-types.md) for the complete table of supported types, their WGSL/GLSL equivalents, and value formats.
+
+### Custom Batcher (extension-based)
+
+The `Batcher` abstract class enables custom batching for specialized rendering. Subclass it and register via extensions:
+
+```ts
+import { Batcher, extensions, ExtensionType } from "pixi.js";
+import type {
+  BatcherOptions,
+  BatchableMeshElement,
+  BatchableQuadElement,
+  Geometry,
+  Shader,
+} from "pixi.js";
+
+class MyBatcher extends Batcher {
+  public static extension = {
+    type: [ExtensionType.Batcher],
+    name: "my-batcher",
+  };
+
+  public name = "my-batcher";
+  protected vertexSize = 6; // floats per vertex
+  public geometry: Geometry;
+  public shader: Shader;
+
+  constructor(options: BatcherOptions) {
+    super(options);
+    // Initialize geometry and shader
+  }
+
+  public packAttributes(
+    element: BatchableMeshElement,
+    float32View: Float32Array,
+    uint32View: Uint32Array,
+    index: number,
+    textureId: number,
+  ): void {
+    // Pack mesh vertex attributes into the batch buffer
+  }
+
+  public packQuadAttributes(
+    element: BatchableQuadElement,
+    float32View: Float32Array,
+    uint32View: Uint32Array,
+    index: number,
+    textureId: number,
+  ): void {
+    // Pack quad vertex attributes into the batch buffer
+  }
+}
+
+extensions.add(MyBatcher);
+```
+
+Elements reference the batcher by `batcherName`. The `BatchableElement` interface requires: `batcherName`, `texture`, `blendMode`, `indexSize`, `attributeSize`, `topology`, and `packAsQuad`.
+
+A custom `InstructionPipe` that caches state per `InstructionSet` (the way `BatcherPipe` keeps its batchers) should implement `destroyInstructionSet(instructionSet)`. The renderer calls it when the owning render group is destroyed, so the cached GPU objects are released with it instead of leaking.
+
+```ts
+public destroyInstructionSet(instructionSet: InstructionSet): void {
+  this._cache[instructionSet.uid]?.destroy();
+  delete this._cache[instructionSet.uid];
+}
+```
+
+## Common Mistakes
+
+### [CRITICAL] Old Shader.from(vertex, fragment, uniforms) constructor
+
+Wrong:
+
+```ts
+const shader = Shader.from(vertex, fragment, { uTime: 1 });
+```
+
+Correct:
+
+```ts
+const shader = Shader.from({
+  gl: { vertex, fragment },
+  resources: {
+    uniforms: new UniformGroup({
+      uTime: { value: 1, type: "f32" },
+    }),
+  },
+});
+```
+
+v8 requires an options object with `gl`/`gpu` programs and `resources`. The positional API was removed.
+
+
+### [CRITICAL] UniformGroup without type annotation
+
+Wrong:
+
+```ts
+new UniformGroup({ uTime: 1 });
+```
+
+Correct:
+
+```ts
+new UniformGroup({ uTime: { value: 1, type: "f32" } });
+```
+
+Every uniform requires an explicit `{ value, type }` pair. Omitting the type causes a runtime error: "Uniform type undefined is not supported."
+
+
+### [HIGH] UBO with unsupported types or wrong structure
+
+UBO mode supports `f32` and `i32` based types (scalars and vectors). `u32` is not in the supported `UniformGroup` type list and will throw. Matrices are float-only (`mat*<f32>`). Samplers cannot be placed in UBOs.
+
+The struct name and field order must exactly match the shader's UBO declaration. Mismatches produce garbled rendering with no error.
+
+
+### [HIGH] Putting textures in UniformGroup
+
+Wrong:
+
+```ts
+new UniformGroup({
+  uTexture: { value: texture, type: "f32" },
+});
+```
+
+Correct:
+
+```ts
+const shader = Shader.from({
+  gl: { vertex, fragment },
+  resources: {
+    uTexture: texture.source,
+    uSampler: texture.source.style,
+    myUniforms: new UniformGroup({
+      uAlpha: { value: 1.0, type: "f32" },
+    }),
+  },
+});
+```
+
+Textures are resources, not uniforms. Pass `texture.source` (TextureSource) and `texture.source.style` (TextureStyle) as top-level resource entries.
+
+
+### [HIGH] Replaying a render bundle against a different render target
+
+Wrong:
+
+```ts
+const bundle = encoder.endBundle();
+// later, on every frame, regardless of what is bound
+encoder.executeBundle(bundle);
+```
+
+Correct:
+
+```ts
+if (!bundle || !encoder.isBundleValid(bundle)) {
+  bundle = record();
+}
+encoder.executeBundle(bundle);
+```
+
+A bundle bakes the attachments and winding of the pass it was recorded in, and the device it was recorded on. Replaying it under a different target either fails WebGPU validation for the whole frame or silently renders inside out; replaying it after a device loss is rejected outright.
+
+
+### [MEDIUM] Reading Geometry.getSize()
+
+`geometry.getSize()` is deprecated since 8.20.0 and logs a warning. Use `geometry.vertexCount`, which is cached and only recomputed when buffers or attributes change.
+
+
+## API Reference
+
+- [Shader](https://pixijs.download/release/docs/rendering.Shader.html.md)
+- [GlProgram](https://pixijs.download/release/docs/rendering.GlProgram.html.md)
+- [GpuProgram](https://pixijs.download/release/docs/rendering.GpuProgram.html.md)
+- [UniformGroup](https://pixijs.download/release/docs/rendering.UniformGroup.html.md)
+- [Filter](https://pixijs.download/release/docs/filters.Filter.html.md)
+- [Batcher](https://pixijs.download/release/docs/rendering.Batcher.html.md)
+- [BatcherPipe](https://pixijs.download/release/docs/rendering.BatcherPipe.html.md)
+- [ShaderOverrides](https://pixijs.download/release/docs/rendering.ShaderOverrides.html.md)
+- [TextureView](https://pixijs.download/release/docs/rendering.TextureView.html.md)
+- [RenderTarget](https://pixijs.download/release/docs/rendering.RenderTarget.html.md)
+- [GpuEncoderSystem](https://pixijs.download/release/docs/rendering.GpuEncoderSystem.html.md)
+- [RenderBundle](https://pixijs.download/release/docs/rendering.RenderBundle.html.md)
+- [Geometry](https://pixijs.download/release/docs/rendering.Geometry.html.md)
+- [State](https://pixijs.download/release/docs/rendering.State.html.md)