@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-blend-modes/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: pixijs-blend-modes
+description: "Use this skill when compositing display objects with blend modes in PixiJS v8. Covers standard modes (normal, add, multiply, screen, erase, min, max), advanced modes via pixi.js/advanced-blend-modes (color-burn, overlay, hard-light, etc.), batch-friendly ordering. Triggers on: blendMode, additive, multiply, screen, overlay, color-burn, color-dodge, advanced-blend-modes, glow, erase."
+license: MIT
+---
+
+Set `container.blendMode` to composite display objects with GPU blend equations (standard modes) or filter-based advanced modes. Blend-mode transitions break render batches, so group like-mode siblings together.
+
+## Quick Start
+
+```ts
+const light = new Sprite(await Assets.load("light.png"));
+light.blendMode = "add";
+app.stage.addChild(light);
+
+const shadow = new Sprite(await Assets.load("shadow.png"));
+shadow.blendMode = "multiply";
+app.stage.addChild(shadow);
+
+import "pixi.js/advanced-blend-modes";
+const overlay = new Sprite(await Assets.load("overlay.png"));
+overlay.blendMode = "color-burn";
+app.stage.addChild(overlay);
+```
+
+**Related skills:** `pixijs-filters` (advanced modes use the filter pipeline), `pixijs-performance` (batching with blend modes), `pixijs-color` (color manipulation).
+
+## Core Patterns
+
+### Standard blend modes
+
+Standard modes are built in and use GPU blend equations directly:
+
+```ts
+import { Sprite } from "pixi.js";
+
+sprite.blendMode = "normal"; // standard alpha compositing (effective default at root)
+sprite.blendMode = "add"; // additive (lighten, glow effects)
+sprite.blendMode = "multiply"; // multiply (darken, shadow effects)
+sprite.blendMode = "screen"; // screen (lighten, dodge effects)
+sprite.blendMode = "erase"; // erase pixels from render target
+sprite.blendMode = "none"; // no blending, overwrites destination
+sprite.blendMode = "inherit"; // inherit from parent (this is the actual default value)
+sprite.blendMode = "min"; // keeps minimum of source and destination (WebGL2+ only)
+sprite.blendMode = "max"; // keeps maximum of source and destination (WebGL2+ only)
+```
+
+These are hardware-accelerated and cheap. They do not require filters.
+
+### Advanced blend modes
+
+Advanced modes require an explicit import to register the extensions. On the WebGL renderer they also require `useBackBuffer: true` at init time, or PixiJS logs a warning and the blend silently falls back:
+
+```ts
+import "pixi.js/advanced-blend-modes";
+import { Application, Sprite, Assets } from "pixi.js";
+
+const app = new Application();
+await app.init({ useBackBuffer: true }); // required for advanced modes on WebGL
+
+const texture = await Assets.load("overlay.png");
+const overlay = new Sprite(texture);
+overlay.blendMode = "color-burn";
+```
+
+Available advanced modes:
+
+| Mode           | Effect                                          |
+| -------------- | ----------------------------------------------- |
+| `color-burn`   | Darkens by increasing contrast                  |
+| `color-dodge`  | Brightens by decreasing contrast                |
+| `darken`       | Keeps darker of two layers                      |
+| `difference`   | Absolute difference                             |
+| `divide`       | Divides bottom by top                           |
+| `exclusion`    | Similar to difference, lower contrast           |
+| `hard-light`   | Multiply or screen based on top layer           |
+| `hard-mix`     | High contrast threshold blend                   |
+| `lighten`      | Keeps lighter of two layers                     |
+| `linear-burn`  | Adds and subtracts to darken                    |
+| `linear-dodge` | Adds layers together                            |
+| `linear-light` | Linear burn or dodge based on top layer         |
+| `luminosity`   | Luminosity of top, hue/saturation of bottom     |
+| `negation`     | Inverted difference                             |
+| `overlay`      | Multiply or screen based on bottom layer        |
+| `pin-light`    | Replaces based on lightness comparison          |
+| `saturation`   | Saturation of top, hue/luminosity of bottom     |
+| `soft-light`   | Gentle overlay effect                           |
+| `subtract`     | Subtracts top from bottom                       |
+| `vivid-light`  | Color burn or dodge based on top layer          |
+| `color`        | Hue and saturation of top, luminosity of bottom |
+
+You set advanced blend modes the same way as standard ones, via the `blendMode` property. They use filters internally, so they cost more than standard modes.
+
+### Batch-friendly ordering
+
+Different blend modes break the rendering batch. Order objects to minimize transitions:
+
+```ts
+import { Container, Sprite } from "pixi.js";
+
+const scene = new Container();
+scene.addChild(screenSprite1); // 'screen'
+scene.addChild(screenSprite2); // 'screen'
+scene.addChild(normalSprite1); // 'normal'
+scene.addChild(normalSprite2); // 'normal'
+```
+
+2 draw calls. Alternating order (`screen, normal, screen, normal`) would produce 4.
+
+## Common Mistakes
+
+### [HIGH] Not importing advanced-blend-modes extension
+
+Wrong:
+
+```ts
+import { Sprite } from "pixi.js";
+
+sprite.blendMode = "color-burn"; // silently falls back to normal
+```
+
+Correct:
+
+```ts
+import "pixi.js/advanced-blend-modes";
+import { Sprite } from "pixi.js";
+
+sprite.blendMode = "color-burn";
+```
+
+Advanced blend modes (color-burn, overlay, etc.) require the extension import. Without it, only standard modes (normal, add, multiply, screen) are available. The invalid mode silently falls back.
+
+
+### [MEDIUM] Mixing blend modes across adjacent objects
+
+Different blend modes break the render batch. `screen / normal / screen / normal` produces 4 draw calls, while `screen / screen / normal / normal` produces 2. Sort children so objects with the same blend mode are adjacent.
+
+
+### [HIGH] Using the v7 BLEND_MODES enum
+
+Wrong:
+
+```ts
+import { BLEND_MODES } from "pixi.js";
+
+sprite.blendMode = BLEND_MODES.ADD; // runtime error: BLEND_MODES is undefined
+```
+
+Correct:
+
+```ts
+sprite.blendMode = "add";
+```
+
+In v8, `BLEND_MODES` is a TypeScript type only (a union of string literals). There is no runtime enum export, so `BLEND_MODES.ADD` evaluates to accessing a property on `undefined`. Use the string form.
+
+
+### [HIGH] Advanced blend modes without useBackBuffer
+
+Wrong:
+
+```ts
+import "pixi.js/advanced-blend-modes";
+await app.init({
+  /* no useBackBuffer */
+});
+sprite.blendMode = "color-burn"; // logs a warning, falls back
+```
+
+Correct:
+
+```ts
+import "pixi.js/advanced-blend-modes";
+await app.init({ useBackBuffer: true });
+sprite.blendMode = "color-burn";
+```
+
+Advanced modes read from the back buffer. On WebGL, the blend silently falls back if the back buffer is not enabled. WebGPU enables the back buffer unconditionally.
+
+
+### [MEDIUM] Advanced blend modes clipped or scaled on high-DPI renderers
+
+Advanced blend modes are filter-based and use `Filter.defaultOptions`, whose resolution defaults to `1`. On a high-DPI render target the blended object can look clipped, scaled, or only partially applied.
+
+Wrong:
+
+```ts
+import "pixi.js/advanced-blend-modes";
+
+sprite.blendMode = "overlay"; // renders at resolution 1, can clip on retina
+```
+
+Correct:
+
+```ts
+import { Filter } from "pixi.js";
+import "pixi.js/advanced-blend-modes";
+
+Filter.defaultOptions.resolution = "inherit"; // set before creating affected objects
+
+sprite.blendMode = "overlay";
+```
+
+Setting `Filter.defaultOptions.resolution = "inherit"` makes advanced blend modes render at the render target's resolution. This costs more memory and runtime, so apply it where fidelity matters.
+
+
+## API Reference
+
+- [Container.blendMode](https://pixijs.download/release/docs/scene.Container.html.md)
+- [OverlayBlend](https://pixijs.download/release/docs/filters.OverlayBlend.html.md)
+- [ColorBurnBlend](https://pixijs.download/release/docs/filters.ColorBurnBlend.html.md)
+- [ColorDodgeBlend](https://pixijs.download/release/docs/filters.ColorDodgeBlend.html.md)
+- [HardLightBlend](https://pixijs.download/release/docs/filters.HardLightBlend.html.md)
+- [SoftLightBlend](https://pixijs.download/release/docs/filters.SoftLightBlend.html.md)
+- [DifferenceBlend](https://pixijs.download/release/docs/filters.DifferenceBlend.html.md)

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

@@ -0,0 +1,299 @@
+---
+name: pixijs-color
+description: "Use this skill when creating, converting, or manipulating colors in PixiJS v8. Covers Color class input formats (hex, CSS names, RGB/HSL objects, arrays, Uint8Array), conversion methods (toHex, toNumber, toArray, toRgba), component access, setAlpha/multiply/premultiply, Color.shared singleton. Triggers on: Color, ColorSource, hex, rgb, hsl, tint, premultiply, Color.shared, color conversion."
+license: MIT
+---
+
+The `Color` class creates and converts colors for tints, fills, strokes, and anywhere PixiJS accepts a `ColorSource`. Most APIs accept raw hex/strings directly, so explicit `new Color(...)` is only needed when converting formats or manipulating values.
+
+## Quick Start
+
+```ts
+const fillColor = new Color("#ff6600");
+console.log(fillColor.toHex()); // '#ff6600'
+console.log(fillColor.toNumber()); // 0xff6600
+console.log(fillColor.toArray()); // [1, 0.4, 0, 1]
+
+const g = new Graphics().rect(0, 0, 200, 100).fill(fillColor);
+app.stage.addChild(g);
+
+const sprite = Sprite.from("hero.png");
+sprite.tint = "dodgerblue";
+app.stage.addChild(sprite);
+
+const t = Color.shared.setValue(0xffffff).multiply([1, 0.5, 0.5]).toNumber();
+sprite.tint = t;
+```
+
+**Related skills:** `pixijs-scene-graphics` (fill/stroke colors), `pixijs-scene-sprite` (tint), `pixijs-blend-modes` (compositing).
+
+## Core Patterns
+
+### Accepted input formats
+
+```ts
+import { Color } from "pixi.js";
+
+// Hex integer
+new Color(0xff0000);
+
+// Hex strings
+new Color("#ff0000");
+new Color("#f00");
+new Color("ff0000");
+
+// CSS color names
+new Color("red");
+new Color("dodgerblue");
+
+// RGB/RGBA objects (components 0-255)
+new Color({ r: 255, g: 0, b: 0 });
+new Color({ r: 255, g: 0, b: 0, a: 0.5 });
+
+// HSL/HSLA objects
+new Color({ h: 0, s: 100, l: 50 });
+new Color({ h: 0, s: 100, l: 50, a: 0.5 });
+
+// HSV/HSVA objects
+new Color({ h: 0, s: 100, v: 100 });
+
+// CSS strings
+new Color("rgb(255, 0, 0)");
+new Color("rgba(255, 0, 0, 0.5)");
+new Color("hsl(0, 100%, 50%)");
+
+// Normalized 0-1 arrays (Float32Array or plain arrays)
+new Color([1, 0, 0]); // RGB
+new Color([1, 0, 0, 0.5]); // RGBA
+
+// Uint8 arrays (components 0-255)
+new Color(new Uint8Array([255, 0, 0]));
+new Color(new Uint8ClampedArray([255, 0, 0, 128]));
+
+// 8-digit hex with alpha
+new Color("#ff0000ff");
+new Color("#f00f");
+
+// Copy from another Color instance
+const red = new Color("red");
+const copy = new Color(red);
+```
+
+### Conversion methods
+
+```ts
+import { Color } from "pixi.js";
+
+const color = new Color("#ff6600");
+
+color.toHex(); // '#ff6600'
+color.toHexa(); // '#ff6600ff' (hex with alpha)
+color.toNumber(); // 0xff6600
+color.toArray(); // [1, 0.4, 0, 1] (normalized RGBA)
+color.toRgbArray(); // [1, 0.4, 0] (normalized RGB, no alpha)
+color.toRgbaString(); // 'rgba(255,102,0,1)'
+color.toRgba(); // { r: 1, g: 0.4, b: 0, a: 1 }
+color.toRgb(); // { r: 1, g: 0.4, b: 0 }
+color.toUint8RgbArray(); // [255, 102, 0]
+
+// setValue() is the chainable way to change a color's value
+color.setValue(0xff0000).toHex(); // '#ff0000'
+```
+
+### Component access
+
+```ts
+import { Color } from "pixi.js";
+
+const color = new Color("rgba(255, 128, 0, 0.8)");
+
+color.red; // 1
+color.green; // ~0.502
+color.blue; // 0
+color.alpha; // 0.8
+```
+
+All component getters return normalized 0-1 values.
+
+### Manipulation
+
+```ts
+import { Color } from "pixi.js";
+
+const color = new Color("red");
+
+// Set alpha (chainable)
+color.setAlpha(0.5);
+
+// Multiply with another color (destructive, modifies in place)
+color.multiply(0x808080);
+
+// Premultiply alpha (destructive, RGB channels multiplied by alpha)
+color.premultiply(0.8);
+
+// Premultiply alpha only (RGB unchanged)
+color.premultiply(0.8, false);
+
+// Chain operations
+new Color("white").setAlpha(0.5).multiply([0.8, 0.2, 0.2]);
+```
+
+`multiply()` and `premultiply()` are destructive; they modify the color and set `value` to null (original format is lost).
+
+### Non-destructive premultiplied output
+
+```ts
+import { Color } from "pixi.js";
+
+const color = new Color("red").setAlpha(0.5);
+
+const packed = color.toPremultiplied(color.alpha); // 0x7F7F0000
+const alphaOnly = color.toPremultiplied(color.alpha, false); // 0x7FFF0000
+```
+
+`toPremultiplied(alpha, applyToRGB?)` returns a 32-bit `0xAARRGGBB` integer without mutating `this`. Use it in batchers and tint math where the source color must be reused. When `applyToRGB` is `false`, only the alpha byte is packed; the RGB stays at its full value.
+
+### Reusing output buffers
+
+```ts
+import { Color } from "pixi.js";
+
+const rgba = new Float32Array(4);
+const rgb = new Float32Array(3);
+const rgb8 = new Uint8Array(3);
+
+app.ticker.add(() => {
+  Color.shared.setValue(sprite.tint).toArray(rgba).toRgbArray(rgb);
+
+  Color.shared.toUint8RgbArray(rgb8);
+});
+```
+
+`toArray(out?)`, `toRgbArray(out?)`, and `toUint8RgbArray(out?)` accept a reusable `number[]`, `Float32Array`, `Uint8Array`, or `Uint8ClampedArray` and write into it. Pass your own buffer in hot paths to avoid allocating per frame; omit the argument and the `Color` instance returns its internal cache array.
+
+### Packing for GPU buffers
+
+| Method                   | Returns                                                      |
+| ------------------------ | ------------------------------------------------------------ |
+| `toBgrNumber()`          | 24-bit `0xBBGGRR` integer with R/B swapped                   |
+| `toLittleEndianNumber()` | Same 24-bit swap, convenient for little-endian vertex writes |
+
+Both are cheap and useful when emitting colors straight into packed vertex attributes.
+
+### Color.shared for temporary operations
+
+```ts
+import { Color } from "pixi.js";
+
+// One-off conversion without allocating a new Color
+const hex = Color.shared.setValue("#ff6600").toNumber();
+const arr = Color.shared.setValue(0xff0000).toArray();
+```
+
+`Color.shared` is a singleton that avoids allocating a new `Color` on every call. This matters in hot paths like render loops or per-frame tint calculations where repeated `new Color()` creates GC pressure. Do not store references to it; other code may mutate it.
+
+```ts
+import { Color } from "pixi.js";
+
+// Good: reuse shared instance in a per-frame callback
+app.ticker.add(() => {
+  const t = performance.now() / 1000;
+  sprite.tint = Color.shared
+    .setValue("white")
+    .multiply([Math.sin(t) * 0.5 + 0.5, 0.2, 0.8])
+    .toNumber();
+});
+```
+
+### Validating input
+
+```ts
+import { Color } from "pixi.js";
+
+Color.isColorLike("red"); // true
+Color.isColorLike("#ff0000"); // true
+Color.isColorLike(0xff0000); // true
+Color.isColorLike([1, 0, 0]); // true
+Color.isColorLike({ r: 1, g: 0, b: 0 }); // true
+Color.isColorLike({ foo: 1 }); // false
+Color.isColorLike(null); // false
+```
+
+`Color.isColorLike()` checks the structural shape (string, number, array, or recognized object). It doesn't validate that a string is a real CSS color name, nor that array values fall in range. Use it as a type guard before passing user input to `new Color()` or `setValue()`.
+
+## Common Mistakes
+
+### [MEDIUM] Expecting toRgba() to return 0-255 values
+
+Wrong:
+
+```ts
+import { Color } from "pixi.js";
+
+const { r, g, b } = new Color({ r: 255, g: 128, b: 0 }).toRgba();
+// r = 1, g = ~0.502, b = 0 (NOT 255, 128, 0)
+```
+
+Correct:
+
+```ts
+import { Color } from "pixi.js";
+
+// Use toUint8RgbArray() for 0-255 output
+const [r, g, b] = new Color({ r: 255, g: 128, b: 0 }).toUint8RgbArray();
+// r = 255, g = 128, b = 0
+```
+
+RGB object _inputs_ use 0-255 range (`{ r: 255, g: 0, b: 0 }`), but all output methods (`toRgba()`, `toRgb()`, `toArray()`, `toRgbArray()`) normalize to 0-1. Use `toUint8RgbArray()` when you need 0-255 integers for CSS or external APIs.
+
+
+### [MEDIUM] Using 0-255 range in color arrays
+
+Wrong:
+
+```ts
+import { Color } from "pixi.js";
+
+new Color([255, 0, 0]); // NOT red; values are interpreted as 0-1
+```
+
+Correct:
+
+```ts
+import { Color } from "pixi.js";
+
+new Color([1, 0, 0]); // red via normalized array
+new Color(0xff0000); // red via hex
+new Color("red"); // red via CSS name
+new Color(new Uint8Array([255, 0, 0])); // red via Uint8Array (0-255)
+```
+
+Plain number arrays (`number[]` and `Float32Array`) use normalized 0-1 range. `[255, 0, 0]` clamps to `[1, 0, 0]` because values are clamped, but `[200, 100, 50]` does not produce the expected color. Use `Uint8Array` or `Uint8ClampedArray` for 0-255 input.
+
+
+### [MEDIUM] Using utils.string2hex or utils.hex2string
+
+Wrong:
+
+```ts
+import { utils } from "pixi.js";
+
+const hex = utils.string2hex("#ff0000");
+```
+
+Correct:
+
+```ts
+import { Color } from "pixi.js";
+
+const hex = new Color("#ff0000").toNumber();
+const str = new Color(0xff0000).toHex();
+```
+
+The `utils` namespace was removed in v8. Use the `Color` class for all color conversions.
+
+
+## API Reference
+
+- [Color](https://pixijs.download/release/docs/color.Color.html.md)
+- [ColorSource](https://pixijs.download/release/docs/color.ColorSource.html.md)

package/vendor/pixijs-skills/skills/pixijs-core-concepts/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: pixijs-core-concepts
+description: "Use this skill when understanding how PixiJS v8 renders frames: the systems-and-pipes renderer, the render loop, and how the library adapts to different environments. Covers WebGLRenderer/WebGPURenderer/CanvasRenderer selection, renderer.render() pipeline, environment detection, rendering into RenderTextures and RenderTargets (flipY, mipLevel, layer, bind/push/pop, copyDepthTexture), WebGL context loss and WebGPU device loss recovery, and pointers to per-topic deep dives. Triggers on: renderer, WebGL, WebGPU, Canvas, render loop, render pipeline, systems, environments, autoDetectRenderer, RenderTexture, RenderTarget, render to texture, flipY, mipLevel, layer, 3D texture, depth slice, renderTarget.bind, copyToTexture, copyDepthTexture, depth-only, WebGLLoader, WebGPULoader, CanvasLoader, RendererLoader, lazy-load renderer systems, code splitting, context lost, webglcontextlost, device lost, GPUDevice.lost."
+license: MIT
+---
+
+Foundational model for how PixiJS v8 gets pixels on the screen: the renderer decides which GPU backend to use, the render loop drives per-frame work, and the environment layer adapts the library to browser, Web Worker, or SSR contexts. For the scene graph itself (Containers, transforms, destroy), see `pixijs-scene-core-concepts`.
+
+## Quick Start
+
+```ts
+console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'
+
+app.ticker.add((ticker) => {
+  sprite.rotation += 0.01 * ticker.deltaTime;
+});
+
+const tex = app.renderer.extract.texture({ target: app.stage });
+
+app.renderer.render({ container: app.stage });
+```
+
+`app.renderer` is the `WebGLRenderer`, `WebGPURenderer`, or `CanvasRenderer` chosen by `autoDetectRenderer`. The TickerPlugin drives `renderer.render()` automatically; call it manually only with `autoStart: false`. Backend selection happens in `Application.init({ preference })`; see `pixijs-application` for setup.
+
+**Related skills:** `pixijs-application` (Application construction and lifecycle), `pixijs-ticker` (per-frame logic, priorities, FPS capping), `pixijs-environments` (Web Worker, SSR, strict CSP), `pixijs-custom-rendering` (writing a RenderPipe), `pixijs-scene-core-concepts` (scene graph basics).
+
+## Topics
+
+| Topic               | Reference                                              | When                                                      |
+| ------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
+| Choosing a backend  | [references/renderers.md](references/renderers.md)     | Preference forms, per-renderer options, systems and pipes |
+| Per-frame execution | [references/render-loop.md](references/render-loop.md) | Priority order, time units, manual rendering              |
+
+For deep dives into any single topic, open the corresponding reference file. Non-browser targets (`DOMAdapter`, `WebWorkerAdapter`, custom adapters, strict CSP) are covered in the `pixijs-environments` skill.
+
+## Decision guide
+
+- **Setting up an Application?** Start with `pixijs-application`. This skill explains what the renderer does under the hood.
+- **Choosing between WebGL and WebGPU?** Use `['webgpu', 'webgl']` as your preference array. WebGPU is fastest where available; WebGL is the reliable fallback. See `references/renderers.md`.
+- **Running in a Web Worker?** Set `DOMAdapter.set(WebWorkerAdapter)` before `app.init`. See the `pixijs-environments` skill for complete setup.
+- **Need manual control over when rendering happens?** Set `autoStart: false` and call `app.renderer.render(app.stage)` from your own loop. See `references/render-loop.md`.
+- **Integrating with a physics library?** Add your update at `UPDATE_PRIORITY.HIGH` so physics runs before the render at `LOW`. See `references/render-loop.md`.
+- **Writing a custom renderable?** Implement a `RenderPipe`. See `pixijs-custom-rendering` skill.
+- **Rendering into a texture or a custom render target?** Pass `target` to `renderer.render()`, or build a `RenderTarget` with explicit color and depth attachments. See `references/renderers.md`.
+- **Running under strict CSP?** Import `'pixi.js/unsafe-eval'`. See the `pixijs-environments` skill.
+
+## Quick concepts
+
+### Renderer = systems + pipes
+
+Each renderer is composed of `Systems` (lifecycle services: textures, buffers, state, filters, masks) and `RenderPipes` (per-renderable instruction builders: sprite, graphics, mesh, particle, text, tiling). Writing a custom renderable means implementing a `RenderPipe` and registering it via extensions. Backend-specific systems and pipes can be dynamic-imported through a renderer loader extension (`WebGLLoader`, `WebGPULoader`, `CanvasLoader`); see `references/renderers.md`.
+
+### The render loop
+
+`app.ticker.add(fn)` registers a callback that runs every frame. The `TickerPlugin` registers `app.render()` at `UPDATE_PRIORITY.LOW`, so ticker callbacks at `NORMAL` or `HIGH` run before the draw. Disable the plugin with `autoStart: false` for manual control.
+
+### Environments
+
+`DOMAdapter` abstracts every DOM call PixiJS makes (canvas creation, image loading, fetch, XML parsing). Swap with `DOMAdapter.set(WebWorkerAdapter)` for Workers or implement a custom `Adapter` for Node/SSR. Must be done before `Application.init`.
+
+## Common Mistakes
+
+### [HIGH] Accessing app.renderer before init() resolves
+
+Wrong:
+
+```ts
+const app = new Application();
+app.init({ width: 800, height: 600 });
+console.log(app.renderer.name); // undefined — init() is async
+```
+
+Correct:
+
+```ts
+const app = new Application();
+await app.init({ width: 800, height: 600 });
+console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'
+```
+
+`Application.init()` is async. `app.renderer`, `app.canvas`, and `app.screen` do not exist until after the promise resolves.
+
+### [HIGH] Setting DOMAdapter after Application.init
+
+Wrong:
+
+```ts
+const app = new Application();
+await app.init({ width: 800, height: 600 });
+DOMAdapter.set(WebWorkerAdapter); // too late — init already allocated resources
+```
+
+Correct:
+
+```ts
+DOMAdapter.set(WebWorkerAdapter);
+const app = new Application();
+await app.init({ width: 800, height: 600 });
+```
+
+The adapter abstracts DOM calls the renderer makes during construction (canvas creation, image loading, fetch). Swap it before `init()` or the wrong adapter is baked into the renderer.
+
+### [MEDIUM] Treating `preference` as a guarantee
+
+Wrong:
+
+```ts
+await app.init({ preference: "webgpu" });
+// assume WebGPU is active
+useWebGPUOnlyFeature(app.renderer);
+```
+
+Correct:
+
+```ts
+await app.init({ preference: "webgpu" });
+if (app.renderer.name === "webgpu") {
+  useWebGPUOnlyFeature(app.renderer);
+}
+```
+
+`preference` is a hint, not a demand. If the browser lacks WebGPU support, PixiJS falls back to WebGL (or Canvas). Always branch on `renderer.name` for backend-specific code.
+
+## API Reference
+
+- [autoDetectRenderer](https://pixijs.download/release/docs/rendering.autoDetectRenderer.html.md)
+- [AbstractRenderer](https://pixijs.download/release/docs/rendering.AbstractRenderer.html.md)
+- [WebGLRenderer](https://pixijs.download/release/docs/rendering.WebGLRenderer.html.md)
+- [WebGPURenderer](https://pixijs.download/release/docs/rendering.WebGPURenderer.html.md)
+- [CanvasRenderer](https://pixijs.download/release/docs/rendering.CanvasRenderer.html.md)
+- [Application](https://pixijs.download/release/docs/app.Application.html.md)
+- [DOMAdapter](https://pixijs.download/release/docs/environment.DOMAdapter.html.md)