@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-application/references/application-options.md

@@ -0,0 +1,314 @@
+# ApplicationOptions reference
+
+Every option accepted by `app.init(options)`. Options come from three type sources merged into a single interface:
+
+- `AutoDetectOptions` → base renderer options (width/height/resolution/etc.)
+- `PixiMixins.ApplicationOptions` → plugin options (`resizeTo`, `autoStart`, `sharedTicker`, `culler`)
+- System defaults → each renderer system (background, view, hello, GC, context, backbuffer, events, graphics) contributes its own options
+
+Options with no default are unset unless you pass them. `Partial<ApplicationOptions>` means everything is optional.
+
+
+## View / canvas
+
+Configures the main canvas and how it maps to CSS pixels.
+
+| Option        | Type      | Default | Description                                                                                                                                                                                 |
+| ------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `width`       | `number`  | `800`   | Initial width in CSS pixels.                                                                                                                                                                |
+| `height`      | `number`  | `600`   | Initial height in CSS pixels.                                                                                                                                                               |
+| `canvas`      | `ICanvas` | —       | Existing `HTMLCanvasElement` (or `OffscreenCanvas`) to render into instead of creating one.                                                                                                 |
+| `view`        | `ICanvas` | —       | **Deprecated since 8.0.0.** Alias for `canvas`.                                                                                                                                             |
+| `resolution`  | `number`  | `1`     | Device pixel ratio. Set to `window.devicePixelRatio` for HiDPI.                                                                                                                             |
+| `autoDensity` | `boolean` | `false` | Scale CSS dimensions of the canvas so `width`/`height` stay in CSS pixels while the backing store matches `resolution`. Only honored on `HTMLCanvasElement` (ignored on `OffscreenCanvas`). |
+| `antialias`   | `boolean` | `false` | GPU MSAA where supported. On WebGL, this only affects the main context — use `useBackBuffer: true` if you need antialiased filtering.                                                       |
+| `depth`       | `boolean` | —       | Allocate a depth buffer for the main view. Always on for WebGL; needed for z-ordered rendering.                                                                                             |
+| `transient`   | `boolean` | `false` | WebGPU only, with `antialias`. Discard the canvas's multisample depth/stencil buffer at the end of each pass, and its colour buffer on GPUs that aren't tile-based (tile-based GPUs already discard colour). Only for apps that never reopen the canvas pass while still needing depth or stencil: no filters or masks popping back onto it, no render with `clear: false`. |
+
+```ts
+await app.init({
+  width: 1280,
+  height: 720,
+  resolution: window.devicePixelRatio,
+  autoDensity: true,
+  antialias: true,
+});
+```
+
+## Background
+
+Controls the clear color applied each frame.
+
+| Option              | Type          | Default    | Description                                                                                                                                                                                  |
+| ------------------- | ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backgroundColor`   | `ColorSource` | `0x000000` | Canvas clear color. Accepts hex, CSS string, `[r, g, b, a]`, or any `ColorSource`.                                                                                                           |
+| `background`        | `ColorSource` | —          | Alias for `backgroundColor`. If both are set, `background` wins.                                                                                                                             |
+| `backgroundAlpha`   | `number`      | `1`        | Clear alpha, `0`–`1`. **Cannot be changed after init** — the backing canvas is allocated with or without alpha support based on this value. Set `< 1` now if you may ever need transparency. |
+| `clearBeforeRender` | `boolean`     | `true`     | Clear the target before each frame. Disable only if you're drawing a full-frame background yourself (e.g. a full-screen sprite).                                                             |
+
+```ts
+await app.init({
+  backgroundColor: 0x1099bb,
+  backgroundAlpha: 1,
+});
+```
+
+## Renderer preference
+
+Picks which renderer gets created.
+
+| Option          | Type                                                      | Default   | Description                                                                                                                                                                                                                                                                                |
+| --------------- | --------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `preference`    | `'webgl' \| 'webgpu' \| 'canvas' \| RendererPreference[]` | `'webgl'` | Pick a preferred renderer. String = try first, then fall back through the default priority (`webgl` → `webgpu` → `canvas`). Array = try only the listed renderers, in order (acts as a blocklist too — anything not listed is excluded). See ["Array form"](#preference-array-form) below. |
+| `webgl`         | `Partial<WebGLOptions>`                                   | —         | Options applied **only** when the WebGL renderer is selected. Merged over the top-level options.                                                                                                                                                                                           |
+| `webgpu`        | `Partial<WebGPUOptions>`                                  | —         | Options applied **only** when the WebGPU renderer is selected.                                                                                                                                                                                                                             |
+| `canvasOptions` | `Partial<CanvasOptions>`                                  | —         | Options applied **only** when the Canvas2D renderer is selected.                                                                                                                                                                                                                           |
+
+### preference: array form
+
+Passing an array to `preference` restricts `autoDetectRenderer` to exactly the listed renderers, in the given order. Any renderer not in the array is **excluded entirely** — the array doubles as a blocklist.
+
+```ts
+// Try WebGPU first, then fall back to WebGL. Never use Canvas2D.
+await app.init({ preference: ["webgpu", "webgl"] });
+
+// Only ever use Canvas2D (e.g. in a WebGL-disabled environment).
+await app.init({ preference: ["canvas"] });
+
+// Skip WebGPU entirely while keeping the default webgl → canvas fallback order.
+await app.init({ preference: ["webgl", "canvas"] });
+```
+
+Contrast with the string form, which falls through the **full** default priority if the first choice fails:
+
+```ts
+// Tries webgpu, then webgl, then canvas — all three are candidates.
+await app.init({ preference: "webgpu" });
+```
+
+Use the array when you need to guarantee a renderer is never picked (e.g. WebGPU is broken on a target device, or you want to forbid Canvas2D's feature subset).
+
+
+## Shared rendering
+
+Apply to every renderer type.
+
+| Option                         | Type      | Default | Description                                                                                                                                                                                                          |
+| ------------------------------ | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `roundPixels`                  | `boolean` | `false` | Round vertex positions to whole pixels at shader time. Eliminates subpixel shimmer for pixel-art but blurs smooth motion.                                                                                            |
+| `skipExtensionImports`         | `boolean` | `false` | Disable automatic import of default extensions. With `true`, import the subsystems you need manually (`import 'pixi.js/accessibility'`, `'pixi.js/app'`, `'pixi.js/events'`, …). Renderer loader extensions (`WebGLLoader`/`WebGPULoader`/`CanvasLoader`) are skipped too, so import any backend-specific plugin modules yourself. Used for custom tree-shaken builds. |
+| `hello`                        | `boolean` | `false` | Log the PixiJS version and renderer type banner to the console on init.                                                                                                                                              |
+| `failIfMajorPerformanceCaveat` | `boolean` | `false` | Fail WebGL context creation if the browser reports major performance issues (blocklisted GPU, software fallback). Set `true` for high-performance apps that should refuse slow paths.                                |
+
+```ts
+await app.init({
+  roundPixels: true,
+  hello: true,
+});
+```
+
+## Graphics
+
+Graphics rendering options.
+
+| Option             | Type     | Default | Description                                                                                |
+| ------------------ | -------- | ------- | ------------------------------------------------------------------------------------------ |
+| `bezierSmoothness` | `number` | `0.5`   | Controls curve tessellation for Graphics bezier paths. Higher = smoother (more triangles). |
+
+```ts
+await app.init({
+  bezierSmoothness: 0.75,
+});
+```
+
+## Ticker (TickerPluginOptions)
+
+Controls the built-in render loop.
+
+| Option         | Type      | Default | Description                                                                                                                                                                                                    |
+| -------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `autoStart`    | `boolean` | `true`  | Start the render loop automatically after `init()` resolves. Setting `false` disables `app.render()` being called each frame, but **does not** stop `Ticker.shared` if you've opted into `sharedTicker: true`. |
+| `sharedTicker` | `boolean` | `false` | Use `Ticker.shared` instead of creating a per-Application ticker. Useful for syncing multiple apps; loses per-app control over start/stop.                                                                     |
+
+See `pixijs-ticker` for the ticker API itself.
+
+```ts
+await app.init({
+  autoStart: false,
+  sharedTicker: false,
+});
+
+function loop() {
+  app.renderer.render(app.stage);
+  requestAnimationFrame(loop);
+}
+loop();
+```
+
+## Resize (ResizePluginOptions)
+
+| Option     | Type                    | Default | Description                                                                                                                                                               |
+| ---------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resizeTo` | `Window \| HTMLElement` | `null`  | Element the renderer should auto-resize to match. `window` resizes to the viewport; an element uses `clientWidth`/`clientHeight`. Leave `null` to opt out of auto-resize. |
+
+The plugin listens for `resize` events on `window` and calls `renderer.resize()`. You can reassign `app.resizeTo` at runtime, and call `app.resize()`, `app.queueResize()`, or `app.cancelResize()` from user code.
+
+```ts
+await app.init({
+  resizeTo: window,
+});
+```
+
+## Culler (CullerPluginOptions)
+
+Opt-in plugin (must `extensions.add(CullerPlugin)` to activate).
+
+| Option                   | Type      | Default                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------ | --------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `culler.updateTransform` | `boolean` | `false` (effectively) | Must be explicitly set to `true` to run transform updates before culling. Otherwise PixiJS skips transform updates, and cull bounds may lag one frame for moving objects. |
+
+```ts
+import { CullerPlugin, extensions } from "pixi.js";
+
+extensions.add(CullerPlugin);
+
+await app.init({
+  culler: { updateTransform: true },
+});
+```
+
+## Events
+
+| Option                     | Type                                                     | Default     | Description                                                                                                                      |
+| -------------------------- | -------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `eventMode`                | `'none' \| 'passive' \| 'auto' \| 'static' \| 'dynamic'` | `'passive'` | Default interaction mode for every container. See `pixijs-events`.                                                               |
+| `eventFeatures.move`       | `boolean`                                                | `true`      | Fire `pointermove`/`mousemove`/`touchmove` + `pointerover`/`pointerout`.                                                         |
+| `eventFeatures.globalMove` | `boolean`                                                | `true`      | Fire `globalpointermove`/`globalmousemove`/`globaltouchmove` regardless of hit target. Expensive; turn off if you don't need it. |
+| `eventFeatures.click`      | `boolean`                                                | `true`      | Fire `pointerdown`/`pointerup`/`click`/`tap`.                                                                                    |
+| `eventFeatures.wheel`      | `boolean`                                                | `true`      | Fire `wheel`.                                                                                                                    |
+
+```ts
+await app.init({
+  eventMode: "static",
+  eventFeatures: {
+    move: true,
+    globalMove: false,
+    click: true,
+    wheel: true,
+  },
+});
+```
+
+## Accessibility
+
+Accessibility options. Pass these on the top-level init options.
+
+| Option                                       | Type      | Default | Description                                                                   |
+| -------------------------------------------- | --------- | ------- | ----------------------------------------------------------------------------- |
+| `accessibilityOptions.enabledByDefault`      | `boolean` | `false` | Enable accessibility overlays immediately instead of waiting for the Tab key. |
+| `accessibilityOptions.debug`                 | `boolean` | `false` | Show the accessibility overlay divs visibly for debugging.                    |
+| `accessibilityOptions.activateOnTab`         | `boolean` | `true`  | Activate overlays when the user presses Tab.                                  |
+| `accessibilityOptions.deactivateOnMouseMove` | `boolean` | `true`  | Deactivate overlays when the mouse moves.                                     |
+
+See `pixijs-accessibility` for the full accessibility API.
+
+```ts
+await app.init({
+  accessibilityOptions: {
+    enabledByDefault: true,
+    activateOnTab: true,
+    deactivateOnMouseMove: true,
+  },
+});
+```
+
+## WebGL-only options
+
+Applied when the WebGL renderer is selected.
+
+| Option                  | Type                                | Default     | Description                                                                                                                                                                                                              |
+| ----------------------- | ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `context`               | `WebGL2RenderingContext \| null`    | `null`      | Use this existing WebGL context instead of creating one. Useful for hand-managing the context or integrating with other renderers.                                                                                       |
+| `powerPreference`       | `'high-performance' \| 'low-power'` | `undefined` | Hint the browser which GPU to pick on multi-GPU systems. If omitted, PixiJS internally passes `'default'` to the GPU context; `'default'` is not settable from user code.                                                |
+| `premultipliedAlpha`    | `boolean`                           | `true`      | Tell the compositor the drawing buffer contains premultiplied-alpha colors. Changing this affects blending math.                                                                                                         |
+| `preserveDrawingBuffer` | `boolean`                           | `false`     | Keep the drawing buffer between frames. Required if you need `canvas.toDataURL()` or `canvas.toBlob()` to capture arbitrary frames.                                                                                      |
+| `preferWebGLVersion`    | `1 \| 2`                            | `2`         | Preferred WebGL version. PixiJS v8 was designed for WebGL2 — WebGL1 is a legacy fallback.                                                                                                                                |
+| `multiView`             | `boolean`                           | `false`     | Enable rendering to multiple canvases from one renderer.                                                                                                                                                                 |
+| `useBackBuffer`         | `boolean`                           | `false`     | Render to an intermediate texture instead of directly to the canvas. Required for advanced blend modes and filters that sample the backdrop. Enables `antialias` on the back buffer independently from the main context. |
+
+```ts
+await app.init({
+  preference: "webgl",
+  webgl: {
+    preferWebGLVersion: 2,
+    useBackBuffer: true,
+    powerPreference: "high-performance",
+  },
+});
+```
+
+## WebGPU-only options
+
+| Option                 | Type                                | Default     | Description                                                                                     |
+| ---------------------- | ----------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
+| `powerPreference`      | `'high-performance' \| 'low-power'` | `undefined` | Hint for `requestAdapter()`.                                                                    |
+| `forceFallbackAdapter` | `boolean`                           | `false`     | Force the software/fallback adapter. For testing only.                                          |
+| `gpu`                  | `{ adapter, device }`               | —           | Use a pre-created `GPUAdapter` + `GPUDevice` pair. Useful for sharing a device between engines. |
+
+```ts
+await app.init({
+  preference: ["webgpu", "webgl"],
+  webgpu: {
+    powerPreference: "high-performance",
+  },
+});
+```
+
+## Garbage collection
+
+All time values are milliseconds.
+
+| Option            | Type      | Default | Description                                                  |
+| ----------------- | --------- | ------- | ------------------------------------------------------------ |
+| `gcActive`        | `boolean` | `true`  | Enable the unified renderer garbage collector.               |
+| `gcMaxUnusedTime` | `number`  | `60000` | How long a resource can go unused before the GC collects it. |
+| `gcFrequency`     | `number`  | `30000` | How often the GC sweep runs.                                 |
+
+### Deprecated (GC — prefer the unified options above)
+
+`TextureGCSystem` and `RenderableGCSystem` still accept these, but they've been deprecated since 8.15.0 in favor of `gcActive`/`gcMaxUnusedTime`/`gcFrequency`. Passing them still works for the deprecation window but logs warnings.
+
+| Option                      | Deprecated since | Replacement                                                 |
+| --------------------------- | ---------------- | ----------------------------------------------------------- |
+| `textureGCActive`           | 8.15.0           | `gcActive`                                                  |
+| `textureGCMaxIdle`          | 8.15.0           | `gcMaxUnusedTime` (note: this is frames; the new API is ms) |
+| `textureGCCheckCountMax`    | 8.15.0           | `gcFrequency` (frames → ms)                                 |
+| `textureGCAMaxIdle`         | 8.3.0            | `textureGCMaxIdle` (typo fix) → now `gcMaxUnusedTime`       |
+| `renderableGCActive`        | 8.15.0           | `gcActive`                                                  |
+| `renderableGCMaxUnusedTime` | 8.15.0           | `gcMaxUnusedTime`                                           |
+| `renderableGCFrequency`     | 8.15.0           | `gcFrequency`                                               |
+
+```ts
+await app.init({
+  gcActive: true,
+  gcMaxUnusedTime: 60_000,
+  gcFrequency: 30_000,
+});
+```
+
+## Per-renderer overrides
+
+`webgl`, `webgpu`, and `canvasOptions` are merged over the top-level options once the selected renderer is known:
+
+```ts
+await app.init({
+  antialias: false,
+  webgl: { antialias: true, useBackBuffer: true },
+  webgpu: { antialias: true },
+  canvasOptions: {
+    /* canvas-specific */
+  },
+});
+```
+
+If WebGL wins, the renderer sees `antialias: true` + `useBackBuffer: true`. If WebGPU wins, just `antialias: true`. The three sub-keys are stripped before the options reach the renderer.

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

@@ -0,0 +1,303 @@
+---
+name: pixijs-assets
+description: "Use this skill when loading and managing resources in PixiJS v8. Covers Assets.init, Assets.load/add/unload, bundles, manifests, background loading, onProgress, caching, spritesheets, video textures, web fonts, bitmap fonts, animated GIFs, compressed textures, SVG as texture or Graphics, resolution detection, per-asset data options, and forcing a specific loader with the parser field (for extension-less URLs). Triggers on: Assets, Assets.load, Assets.init, loadBundle, manifest, backgroundLoad, Spritesheet, Cache, LoadOptions, unload, parser, loadParser, loadWebFont, loadBitmapFont, loadVideoTextures, GifSource, VideoSourceOptions."
+license: MIT
+---
+
+The `Assets` API is PixiJS's asset loader, resolver, and cache in one singleton. Use it to load textures, video, spritesheets, fonts, JSON, and other resources with format detection, resolution switching, bundle grouping, progress tracking, and GPU cleanup.
+
+## Quick Start
+
+```ts
+await Assets.init({ basePath: "/static/" });
+
+const texture = await Assets.load("bunny.png");
+const sprite = new Sprite(texture);
+app.stage.addChild(sprite);
+
+const [hero, enemy] = await Assets.load(["hero.png", "enemy.png"]);
+
+await Assets.load({
+  alias: "logo",
+  src: "logo.webp",
+});
+
+const logo = new Sprite(Assets.get("logo"));
+```
+
+`Assets.init()` is optional but recommended for setting `basePath`, `texturePreference`, or a manifest. After init, call `Assets.load()` with a URL, alias, array, or `UnresolvedAsset`; resolved assets are cached and re-resolved by `Assets.get()`.
+
+## Supported file types
+
+| Type                | Extensions                                                       | Parser ID                     | Loader                                                                                                                          |
+| ------------------- | ---------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Textures            | `.png`, `.jpg`, `.jpeg`, `.webp`, `.avif`                        | `texture`                     | `loadTextures`                                                                                                                  |
+| SVG                 | `.svg`                                                           | `svg`                         | `loadSvg` (see `references/svg.md`)                                                                                             |
+| Video textures      | `.mp4`, `.m4v`, `.webm`, `.ogg`, `.ogv`, `.h264`, `.avi`, `.mov` | `video`                       | `loadVideoTextures` (see `references/video.md`)                                                                                 |
+| Sprite sheets       | `.json` (Spritesheet format)                                     | `spritesheet`                 | `spritesheetAsset` (see `references/spritesheet.md`)                                                                            |
+| Bitmap fonts        | `.fnt`, `.xml`                                                   | `bitmap-font`                 | `loadBitmapFont` (loading works by default; rendering `BitmapText` requires `'pixi.js/text-bitmap'`; see `references/fonts.md`) |
+| Web fonts           | `.ttf`, `.otf`, `.woff`, `.woff2`                                | `web-font`                    | `loadWebFont` (see `references/fonts.md`)                                                                                       |
+| JSON                | `.json`                                                          | `json`                        | `loadJson`                                                                                                                      |
+| Text                | `.txt`                                                           | `text`                        | `loadTxt`                                                                                                                       |
+| Compressed textures | `.basis`, `.dds`, `.ktx`, `.ktx2`                                | `basis`, `dds`, `ktx`, `ktx2` | See `references/compressed-textures.md`                                                                                         |
+| Animated GIFs       | `.gif`                                                           | `gif`                         | Requires `'pixi.js/gif'`; returns `GifSource` (see `references/gif.md`)                                                         |
+
+The **Parser ID** column is the value you pass to the top-level `parser` field on an asset descriptor to force a specific loader. See "Forcing a parser" below.
+
+## Forcing a parser with `parser`
+
+By default, PixiJS picks a loader by matching the file extension or MIME type. When your URL lacks an extension (CDN signed URLs, blob URLs, API endpoints, content-hashed paths), the resolver can't tell the loader what to do. Set the top-level `parser` field on the asset descriptor to force a specific loader:
+
+```ts
+// Signed CDN URL with no extension
+const texture = await Assets.load({
+  src: "https://cdn.example.com/signed/abc123?token=xyz",
+  parser: "texture",
+});
+
+// API endpoint that returns JSON
+const data = await Assets.load({
+  alias: "config",
+  src: "https://api.example.com/v1/config",
+  parser: "json",
+});
+
+// Extension-less font URL with explicit family
+await Assets.load({
+  src: "https://cdn.example.com/fonts/hero-v2",
+  parser: "web-font",
+  data: { family: "Hero", weights: ["400", "700"] },
+});
+
+// Video stream without a file extension
+const clipTexture = await Assets.load({
+  src: "https://cdn.example.com/stream/xyz",
+  parser: "video",
+  data: { mime: "video/mp4", muted: true, playsinline: true },
+});
+```
+
+The `parser` field goes at the top level of the asset descriptor (alongside `src` and `data`), not inside `data`. It takes any parser ID from the "Supported file types" table above:
+
+- `'texture'`, `'svg'`, `'video'`: image, SVG, and video textures
+- `'json'`, `'text'`: JSON and plain text
+- `'web-font'`, `'bitmap-font'`: web and bitmap fonts
+- `'spritesheet'`: texture atlas JSON
+- `'gif'`: animated GIFs (requires `'pixi.js/gif'`)
+- `'basis'`, `'dds'`, `'ktx'`, `'ktx2'`: compressed textures (each requires its side-effect import)
+
+### When you need it
+
+- **Signed CDN URLs**: `https://cdn.example.com/get?id=abc123` has no extension the loader can test against.
+- **Blob or ObjectURL**: `URL.createObjectURL(blob)` produces `blob:...` URLs with no extension.
+- **Custom routing**: `/api/assets/hero-v2` where the server decides the content type.
+- **Content-hashed paths without suffix**: some build pipelines produce names like `/static/abc123def` instead of `/static/abc123def.png`.
+
+If the URL _does_ have an extension, you don't need `parser`; let auto-detection do its job. Only set `parser` when detection can't work.
+
+### `loadParser` is deprecated
+
+The v7 `loadParser` field still works but emits a deprecation warning. Use `parser` for new code.
+
+```ts
+// Old (deprecated)
+await Assets.load({ src: "...", loadParser: "loadTextures" });
+
+// New
+await Assets.load({ src: "...", parser: "texture" });
+```
+
+## Topics
+
+Every asset workflow is covered in a reference file. Pick the one that matches the question:
+
+| Topic                          | Reference                                                              | When                                        |
+| ------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------- |
+| Texture atlases and animations | [references/spritesheet.md](references/spritesheet.md)                 | Loading sprite sheets with `AnimatedSprite` |
+| Video textures                 | [references/video.md](references/video.md)                             | `.mp4`, `.webm`, autoplay, looping, mobile  |
+| Web and bitmap fonts           | [references/fonts.md](references/fonts.md)                             | `.woff2`, `.fnt`, font families, SDF fonts  |
+| Animated GIFs                  | [references/gif.md](references/gif.md)                                 | `.gif`, `GifSprite`, playback control       |
+| Grouping assets by feature     | [references/bundles.md](references/bundles.md)                         | `addBundle`, `loadBundle`, `unloadBundle`   |
+| Declaring everything upfront   | [references/manifests.md](references/manifests.md)                     | `Assets.init({ manifest })` workflows       |
+| Cache lookups and cleanup      | [references/caching.md](references/caching.md)                         | `Assets.get`, `Assets.unload`, `Cache`      |
+| Priming future assets          | [references/background.md](references/background.md)                   | `backgroundLoad`, `backgroundLoadBundle`    |
+| Loading screens                | [references/progress.md](references/progress.md)                       | `onProgress`, LoadOptions progress          |
+| GPU-compressed formats         | [references/compressed-textures.md](references/compressed-textures.md) | `.ktx2`, `.basis`, `.dds`, `.ktx`           |
+| Vector vs raster SVG           | [references/svg.md](references/svg.md)                                 | `parseAsGraphicsContext`, texture mode      |
+| Retina + format detection      | [references/resolution.md](references/resolution.md)                   | `@{1,2}x`, `format` preferences             |
+
+## Decision guide
+
+- **Need to load a single image?** Use `Assets.load(url)`. No setup required.
+- **Loading many assets grouped by level/scene?** Use a bundle. See `references/bundles.md`.
+- **Know all assets at build time?** Use a manifest in `Assets.init`. See `references/manifests.md`.
+- **Need a loading bar?** Pass a progress callback to `Assets.load`. See `references/progress.md`.
+- **Smooth transitions between levels?** Background-load the next level. See `references/background.md`.
+- **Memory budget matters?** Use compressed textures and `Assets.unload` between screens. See `references/compressed-textures.md` and `references/caching.md`.
+- **Need crisp SVG icons at any size?** Load as Graphics, not texture. See `references/svg.md`.
+- **Retina + WebP/AVIF?** Configure `texturePreference` and use format patterns. See `references/resolution.md`.
+
+## Load options and error handling
+
+There are two separate "options" concepts when loading assets:
+
+1. **`LoadOptions`**: the second argument to `Assets.load`/`loadBundle`. Controls error recovery, retries, progress, and completion callbacks across a whole load.
+2. **`data`**: a field on each asset descriptor. Forwards parser-specific options (scale mode, resolution, font family, autoplay flags, etc.) to the specific loader for that asset.
+
+### LoadOptions (per call)
+
+```ts
+await Assets.load(["hero.png", "enemy.png"], {
+  onProgress: (p) => updateBar(p),
+  onError: (err, url) => {
+    const src = typeof url === "string" ? url : url.src;
+    console.warn("failed:", src, err);
+  },
+  strategy: "retry",
+  retryCount: 3,
+  retryDelay: 250,
+});
+```
+
+- `onProgress(progress)`: `[0, 1]` as assets in the call complete.
+- `onError(error, url)`: `url` is `string | ResolvedAsset`. Guard before reading `.src`; when `url` is a string, `.src` is undefined.
+- `strategy: 'throw' | 'skip' | 'retry'` — default `'throw'`. `'skip'` resolves with any successful assets; `'retry'` reattempts the failed ones.
+- `retryCount` — default `3`, retries per asset when `strategy` is `'retry'`.
+- `retryDelay` — default `250` ms between retries.
+
+Global defaults live on `Loader.defaultOptions`, or pass `loadOptions` to `Assets.init()`.
+
+### `data` options (per asset)
+
+Each loader parser reads its own options from the `data` field on the asset descriptor. Use the table below to pick the right options for each asset type:
+
+| Asset type         | `data` shape                                                                    | Key options                                                                                                                                                                                                                                                | Reference                           |
+| ------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| Texture (image)    | `TextureSourceOptions`                                                          | `resolution`, `scaleMode`, `alphaMode`, `autoGenerateMipmaps`, `antialias`, `addressMode`                                                                                                                                                                  | `references/resolution.md`          |
+| SVG                | `{ parseAsGraphicsContext?, resolution? }`                                      | `parseAsGraphicsContext` for Graphics mode; `resolution` for sharper raster                                                                                                                                                                                | `references/svg.md`                 |
+| Video              | `VideoSourceOptions`                                                            | `autoPlay`, `loop`, `muted`, `playsinline`, `preload`, `updateFPS`, `crossorigin`, `mime`                                                                                                                                                                  | `references/video.md`               |
+| Web font           | `LoadFontData`                                                                  | `family`, `weights`, `style`, `display`, `unicodeRange`, `featureSettings`                                                                                                                                                                                 | `references/fonts.md`               |
+| Bitmap font        | (none; auto-configured)                                                         | Distance-field detection sets scale mode and mipmaps                                                                                                                                                                                                       | `references/fonts.md`               |
+| Spritesheet        | `{ texture?, imageFilename?, ignoreMultiPack?, textureOptions?, cachePrefix? }` | `textureOptions` forwards `TextureSourceOptions` (e.g. `scaleMode`) to the atlas image; `texture` to skip image load; `imageFilename` to override the referenced image; `ignoreMultiPack` to skip multi-pack follow-ups; `cachePrefix` to namespace frames | `references/spritesheet.md`         |
+| GIF                | `GifBufferOptions`                                                              | `fps`, `scaleMode`, `resolution`, `autoGenerateMipmaps`                                                                                                                                                                                                    | `references/gif.md`                 |
+| Compressed texture | `TextureSourceOptions`                                                          | `scaleMode`, `addressMode`, `autoGenerateMipmaps`                                                                                                                                                                                                          | `references/compressed-textures.md` |
+| JSON / Text        | (none)                                                                          | Returned as-is                                                                                                                                                                                                                                             | —                                   |
+
+Example combining `LoadOptions` and `data`:
+
+```ts
+await Assets.load(
+  {
+    alias: "hero",
+    src: "hero.png",
+    data: { scaleMode: "nearest", resolution: 2 },
+  },
+  { strategy: "retry", retryCount: 3 },
+);
+```
+
+Inside a manifest or bundle, every entry can carry its own `data`:
+
+```ts
+await Assets.init({
+  manifest: {
+    bundles: [
+      {
+        name: "level1",
+        assets: [
+          { alias: "tiles", src: "tiles.png", data: { scaleMode: "nearest" } },
+          { alias: "font", src: "hero.woff2", data: { family: "Hero" } },
+          {
+            alias: "clip",
+            src: "intro.mp4",
+            data: { autoPlay: false, muted: true },
+          },
+        ],
+      },
+    ],
+  },
+});
+```
+
+## Runtime configuration
+
+`Assets.init(options)` accepts, alongside `basePath` and `manifest`:
+
+- `defaultSearchParams` — string or `Record<string, any>` appended to every resolved URL. Useful for cache busting.
+- `skipDetections: boolean` — bypass browser format detection for faster init. Requires explicit `texturePreference.format`.
+- `bundleIdentifier: BundleIdentifierOptions` — customize how bundle keys resolve so the same alias can live in multiple bundles.
+- `loadOptions: Partial<LoadOptions>` — set the default `strategy`, `retryCount`, `retryDelay`, and callbacks for every subsequent `Assets.load` call.
+- `preferences: Partial<AssetsPreferences>` — `crossOrigin`, `preferWorkers`, `preferCreateImageBitmap`, `parseAsGraphicsContext`.
+
+After init, preferences can still be tuned:
+
+```ts
+Assets.setPreferences({
+  crossOrigin: "anonymous",
+  preferCreateImageBitmap: false,
+});
+
+for (const detection of Assets.detections) {
+  console.log(detection.extension);
+}
+
+Assets.reset();
+```
+
+- `Assets.setPreferences(preferences)` — push new preferences to every parser that supports them.
+- `Assets.detections` — getter exposing the registered `FormatDetectionParser` list; use when inspecting what formats the current environment advertises.
+- `Assets.reset()` — internal full reset (resolver + loader + cache). Intended for tests so a fresh `Assets.init` can run.
+
+## Common Mistakes
+
+### [CRITICAL] Using `Texture.from(url)` to load
+
+Wrong:
+
+```ts
+const texture = Texture.from("https://example.com/image.png");
+```
+
+Correct:
+
+```ts
+const texture = await Assets.load("https://example.com/image.png");
+```
+
+In v8, `Texture.from()` only reads the cache. It does not fetch from a URL. Use `Assets.load()` first; the return value is the texture itself.
+
+
+### [HIGH] Using positional `Assets.add` signature
+
+Wrong:
+
+```ts
+Assets.add("bunny", "bunny.png");
+```
+
+Correct:
+
+```ts
+Assets.add({ alias: "bunny", src: "bunny.png" });
+```
+
+The positional `Assets.add(key, url)` form was removed in v8. Use the options object with `alias` and `src` properties.
+
+
+### [HIGH] Not unloading textures between levels
+
+`Assets.load()` caches textures indefinitely. For level-based games or screens with distinct asset sets, call `Assets.unloadBundle()` when transitioning to release GPU memory.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [Loader](https://pixijs.download/release/docs/assets.Loader.html.md)
+- [Resolver](https://pixijs.download/release/docs/assets.Resolver.html.md)
+- [Cache](https://pixijs.download/release/docs/assets.Cache.html.md)
+- [LoadOptions](https://pixijs.download/release/docs/assets.LoadOptions.html.md)
+- [AssetInitOptions](https://pixijs.download/release/docs/assets.AssetInitOptions.html.md)
+- [AssetsManifest](https://pixijs.download/release/docs/assets.AssetsManifest.html.md)
+- [AssetsBundle](https://pixijs.download/release/docs/assets.AssetsBundle.html.md)
+- [BackgroundLoader](https://pixijs.download/release/docs/assets.BackgroundLoader.html.md)
+- [Spritesheet](https://pixijs.download/release/docs/assets.Spritesheet.html.md)