@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/constructor-options.md

@@ -0,0 +1,155 @@
+# Constructor options (Container-inherited)
+
+Prefer `new X({ ... })` over line-by-line property assignment when constructing Container-derived scene nodes.
+
+## Before / after
+
+Line-by-line:
+
+```ts
+const hero = new Sprite(texture);
+hero.x = 100;
+hero.y = 200;
+hero.anchor.set(0.5);
+hero.scale.set(2);
+hero.rotation = Math.PI / 4;
+hero.alpha = 0.8;
+hero.tint = 0xff8800;
+hero.label = "hero";
+hero.zIndex = 10;
+```
+
+Options object:
+
+```ts
+const hero = new Sprite({
+  texture,
+  x: 100,
+  y: 200,
+  anchor: 0.5,
+  scale: 2,
+  rotation: Math.PI / 4,
+  alpha: 0.8,
+  tint: 0xff8800,
+  label: "hero",
+  zIndex: 10,
+});
+```
+
+## Exceptions (line-by-line is fine here)
+
+- Values calculated after construction — e.g., `sprite.position.set(app.screen.width / 2, app.screen.height / 2)` needs `app` to exist first.
+- Properties that change at runtime and the change is the point of the example — e.g., `sprite.tint = damageColor` in a damage-flash demo.
+- Objects received from elsewhere — you can't reconstruct them through a constructor options bag.
+- `point.set(x, y)` / `scale.set(sx, sy)` for multi-coordinate batches where a single call reads better than two options keys.
+
+For v7 to v8 migration of constructor patterns, see `pixijs-migration-v8`.
+
+## Worked example
+
+```ts
+const group = new Container({
+  // Transform
+  x: 100,
+  y: 200,
+  scale: { x: 2, y: 2 },
+  rotation: Math.PI / 4,
+  pivot: { x: 50, y: 50 },
+  skew: { x: 0, y: 0 },
+  // Display
+  alpha: 0.8,
+  tint: 0xff8800,
+  blendMode: "add",
+  visible: true,
+  renderable: true,
+  // Hierarchy
+  label: "world",
+  children: [background, player],
+  // Sorting & grouping
+  isRenderGroup: true,
+  sortableChildren: true,
+  zIndex: 10,
+  // Layout & bounds
+  boundsArea: new Rectangle(0, 0, 800, 600),
+  // Effects
+  filters: [new BlurFilter(2)],
+  mask: maskGraphics,
+  // Callbacks
+  onRender: (renderer) => {
+    /* per-frame logic */
+  },
+});
+```
+
+## Transform
+
+| Option     | Type                  | Default           | Description                                                                   |
+| ---------- | --------------------- | ----------------- | ----------------------------------------------------------------------------- |
+| `alpha`    | `number`              | `1`               | Opacity multiplied with parent alpha; 0 is fully transparent, 1 fully opaque. |
+| `angle`    | `number`              | `0`               | Rotation in degrees. Alias for `rotation` in radians.                         |
+| `origin`   | `PointData \| number` | `new Point(0, 0)` | Center of rotation and scaling without moving the node's position.            |
+| `pivot`    | `PointData \| number` | `new Point(0, 0)` | Center of rotation, scaling, and skewing; reprojects position.                |
+| `position` | `PointData`           | `new Point(0, 0)` | Position in parent-local coordinates.                                         |
+| `rotation` | `number`              | `0`               | Rotation in radians.                                                          |
+| `scale`    | `PointData \| number` | `new Point(1, 1)` | Local scale factor along each axis.                                           |
+| `skew`     | `PointData`           | `new Point(0, 0)` | Skew factor in radians along each axis.                                       |
+| `x`        | `number`              | `0`               | Alias for `position.x`.                                                       |
+| `y`        | `number`              | `0`               | Alias for `position.y`.                                                       |
+
+## Display
+
+| Option       | Type          | Default    | Description                                                              |
+| ------------ | ------------- | ---------- | ------------------------------------------------------------------------ |
+| `blendMode`  | `BLEND_MODES` | `'normal'` | How this node composites against its target.                             |
+| `renderable` | `boolean`     | `true`     | When false, skips rendering but still updates transforms.                |
+| `tint`       | `ColorSource` | `0xFFFFFF` | Color multiplied into this node's output; `0xFFFFFF` is no tint.         |
+| `visible`    | `boolean`     | `true`     | When false, skips both rendering and transform updates for this subtree. |
+
+## Hierarchy
+
+| Option     | Type        | Default | Description                                                             |
+| ---------- | ----------- | ------- | ----------------------------------------------------------------------- |
+| `children` | `C[]`       | `[]`    | Array of children to `addChild` after construction.                     |
+| `label`    | `string`    | `null`  | Instance label used by `getChildByLabel` / `getChildrenByLabel`.        |
+| `parent`   | `Container` | `null`  | Parent container; the new node is added as a child during construction. |
+
+## Sorting & grouping
+
+| Option             | Type      | Default | Description                                                                        |
+| ------------------ | --------- | ------- | ---------------------------------------------------------------------------------- |
+| `isRenderGroup`    | `boolean` | `false` | Marks this container as a render group; GPU-level transform for the whole subtree. |
+| `sortableChildren` | `boolean` | `false` | Before rendering, re-sorts children by `zIndex`.                                   |
+| `zIndex`           | `number`  | `0`     | Sort key used when the parent has `sortableChildren` enabled.                      |
+
+## Layout & bounds
+
+| Option       | Type        | Default     | Description                                                   |
+| ------------ | ----------- | ----------- | ------------------------------------------------------------- |
+| `boundsArea` | `Rectangle` | `undefined` | Override bounds rectangle; skips recursive child measurement. |
+| `height`     | `number`    | `0`         | Requested height in pixels; internally assigns `scale.y`.     |
+| `width`      | `number`    | `0`         | Requested width in pixels; internally assigns `scale.x`.      |
+
+## Effects
+
+| Option    | Type                          | Default | Description                                                                     |
+| --------- | ----------------------------- | ------- | ------------------------------------------------------------------------------- |
+| `filters` | `Filter \| readonly Filter[]` | `null`  | One filter or an array of filters applied to this subtree (WebGL/WebGPU only).  |
+| `mask`    | `Container \| number \| null` | `null`  | Mask display object or mask id; picks stencil/alpha/scissor/color mask by type. |
+
+## Callbacks
+
+| Option     | Type                                     | Default | Description                                                        |
+| ---------- | ---------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `onRender` | `((renderer: Renderer) => void) \| null` | `null`  | Per-frame callback invoked while this container is being rendered. |
+
+## Advanced options and aliases
+
+- `autoGarbageCollect` (@advanced, from `ViewContainerOptions`): leave at default unless you know why you need otherwise.
+- `cacheAsTexture`: typed as a constructor option via `CacheAsTextureMixinConstructor` but is ACTUALLY A METHOD on the instance — `container.cacheAsTexture(true)`. Passing it as an options key is accepted but semantically wrong. Prefer the method.
+- `setMask`: typed on `EffectsMixinConstructor` but is also a method, not data. Use `mask: ...` in options or call `setMask(...)` later.
+- `interactive`: convenience boolean that maps to `eventMode`; `true` sets `eventMode = 'static'`, `false` sets `eventMode = 'passive'`. See `eventMode` for the full set of modes.
+- `effects`: the `Container` constructor explicitly passes `effects: true` to `assignWithIgnore`, so passing this option is silently dropped. Not useful.
+
+## See also
+
+Events (`eventMode`, `hitArea`, `cursor`, `interactive*`, `on*` handlers), accessibility (`accessible*`, `tabIndex`, `accessibleTitle`, etc.), and culling (`cullable`, `cullArea`, `cullableChildren`) are ALSO valid constructor options via mixin extension on `ContainerOptions`. They are documented in their own skills: `pixijs-events`, `pixijs-accessibility`, `pixijs-performance`.

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/container-hierarchy.md

@@ -0,0 +1,232 @@
+# Container Hierarchy
+
+The PixiJS scene graph is a tree of `Container` subclasses rooted at `app.stage`. Every node has a single parent, zero or more children, and a local transform. Use this reference for mental model and fine-grained parent/child management; for full Container API (constructor options, lifecycle methods), see the top-level `pixijs-scene-container` skill.
+
+## Quick Start
+
+```ts
+const world = new Container({ label: "world" });
+app.stage.addChild(world);
+
+const hero = new Container({ label: "hero" });
+hero.addChild(new Sprite(bodyTexture));
+hero.addChild(new Sprite(weaponTexture));
+world.addChild(hero);
+
+const enemies = new Container({ label: "enemies" });
+world.addChild(enemies);
+
+enemies.addChild(new Sprite(enemyTexture), new Sprite(enemyTexture));
+```
+
+Every display object in v8 is a `Container` subclass. Leaves (Sprite, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite) have `allowChildren = false` and must not have children. Use a plain `Container` to group leaves.
+
+## Core Patterns
+
+### Add, remove, swap
+
+```ts
+// Add (variadic, returns the first added child)
+parent.addChild(child1, child2, child3);
+
+// Insert at index
+parent.addChildAt(child, 0);
+
+// Remove
+parent.removeChild(child);
+parent.removeChildAt(0);
+parent.removeChildren();
+parent.removeChildren(0, 3); // first three
+
+// Swap
+parent.swapChildren(childA, childB);
+```
+
+`addChild` with an existing parent first removes the child from its old parent (no explicit `removeChild` needed). Returned value is the first added child for chaining.
+
+When `addChildAt` moves a child that is **already** in the same container, the move is silent: no `added` / `removed` / `childAdded` / `childRemoved` events fire, because the parent-child relationship hasn't changed.
+
+### Replacing a child
+
+```ts
+parent.replaceChild(oldChild, newChild);
+```
+
+`replaceChild` swaps `oldChild` for `newChild` at the same index and copies the old child's local transform (position, rotation, scale, etc.) onto the replacement. Use this when you want a drop-in replacement to inherit the old child's placement without copying fields by hand.
+
+### Child queries
+
+```ts
+const count = parent.children.length;
+const first = parent.getChildAt(0);
+const index = parent.getChildIndex(child);
+
+const hero = parent.getChildByLabel("hero");
+const heroDeep = parent.getChildByLabel("weapon", true); // recursive
+
+const enemies = parent.getChildrenByLabel("enemy");
+const waves = parent.getChildrenByLabel(/^wave-\d+/);
+const buttonsDeep = parent.getChildrenByLabel("button", true);
+```
+
+`label` can be a `string` or a `RegExp` (e.g., `parent.getChildByLabel(/^hero-/)`). `getChildByLabel` returns the first match; `getChildrenByLabel` returns every match. Both walk the immediate children and recurse when the second argument is `true`. For more complex queries, iterate `parent.children` manually.
+
+### Iterating children
+
+```ts
+for (const child of parent.children) {
+  child.alpha = 0.5;
+}
+
+parent.children.forEach((child, i) => {
+  child.y = i * 32;
+});
+```
+
+`children` is a plain array. It's safe to iterate, but mutating it during iteration (via `addChild` / `removeChild`) is not; snapshot first with `[...parent.children]` if you need to modify the list.
+
+### Reparenting with transform preservation
+
+```ts
+newParent.reparentChild(child);
+
+newParent.reparentChildAt(child, 0);
+
+newParent.reparentChild(childA, childB, childC);
+```
+
+`reparentChild` and `reparentChildAt` move children to a new parent while preserving their **world** transform, so the visuals don't jump. `reparentChild` appends to the end and accepts multiple children; `reparentChildAt` inserts at a specific index and accepts one child.
+
+If you must do this manually (for example, to batch with other transform work), convert through `getGlobalPosition` and `toLocal`:
+
+```ts
+const globalPos = child.getGlobalPosition();
+newParent.addChild(child);
+child.position = newParent.toLocal(globalPos);
+```
+
+Plain `addChild` keeps the local transform, which means the visual position changes; `reparentChild` is almost always what you want.
+
+### Destroying sub-trees
+
+```ts
+branch.destroy({ children: true });
+```
+
+`destroy()` unlinks a single node. `destroy({ children: true })` recursively tears down the entire sub-tree. Always use `{ children: true }` when removing a branch; otherwise you leak the child nodes and their textures.
+
+### Label-based tree navigation
+
+```ts
+const panel = new Container({ label: "panel" });
+panel.addChild(new Container({ label: "header" }));
+panel.addChild(new Container({ label: "body" }));
+
+const header = panel.getChildByLabel("header");
+```
+
+Use `label` for debug tooling and light-weight tree navigation. Don't use it for hot-path code; the `getChildByLabel` walk is O(n) per call.
+
+### Lifecycle events
+
+Containers emit events for hierarchy changes, visibility changes, and destruction.
+
+**Parent-side events** fire on the container whose children changed:
+
+```ts
+group.on("childAdded", (child, parent, index) => {
+  /* ... */
+});
+group.on("childRemoved", (child, parent, index) => {
+  /* ... */
+});
+```
+
+**Child-side events** fire on the child itself when its parent changes:
+
+```ts
+sprite.on("added", (parent) => {
+  /* ... */
+});
+sprite.on("removed", (oldParent) => {
+  /* ... */
+});
+```
+
+**Property and lifecycle events:**
+
+```ts
+container.on("visibleChanged", (visible) => {
+  /* ... */
+});
+container.on("destroyed", (container) => {
+  /* ... */
+});
+```
+
+`visibleChanged` fires whenever `container.visible` flips. `destroyed` fires inside `destroy()` after internal cleanup but before listeners are removed. By the time `destroyed` runs, `position`, `scale`, `pivot`, `origin`, `skew`, and `parent` have already been nulled, and `children` has been emptied (length 0, but the array reference itself is not nulled). Capture any container state you need **before** calling `destroy()`, not inside the event handler.
+
+## Common Mistakes
+
+### [CRITICAL] Adding children to a leaf
+
+Wrong:
+
+```ts
+sprite.addChild(otherSprite);
+```
+
+Correct:
+
+```ts
+const group = new Container();
+group.addChild(sprite, otherSprite);
+```
+
+Sprite, Graphics, Text, Mesh, ParticleContainer, DOMContainer, and GifSprite all set `allowChildren = false`. Adding children logs a deprecation warning and will become a hard error. Use a plain `Container` to group.
+
+
+### [HIGH] Destroying the parent without `children: true`
+
+Wrong:
+
+```ts
+levelContainer.destroy();
+```
+
+Correct:
+
+```ts
+levelContainer.destroy({ children: true });
+```
+
+Plain `destroy()` only removes the parent. Its children become orphans; still in memory, still referencing textures. For a clean teardown, always pass `{ children: true }`, and include `texture: true` / `textureSource: true` when you also want to release GPU memory.
+
+
+### [MEDIUM] Mutating `children` during iteration
+
+Wrong:
+
+```ts
+parent.children.forEach((child) => {
+  if (shouldRemove(child)) parent.removeChild(child);
+});
+```
+
+Correct:
+
+```ts
+for (const child of [...parent.children]) {
+  if (shouldRemove(child)) parent.removeChild(child);
+}
+```
+
+`removeChild` splices the array, shifting indices. Iterating the live array misses elements or processes some twice. Snapshot before iterating.
+
+
+## API Reference
+
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)
+- [ContainerOptions](https://pixijs.download/release/docs/scene.ContainerOptions.html.md)
+- [ContainerChild](https://pixijs.download/release/docs/scene.ContainerChild.html.md)
+- [ChildrenHelperMixin](https://pixijs.download/release/docs/scene.ChildrenHelperMixin.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/layers.md

@@ -0,0 +1,145 @@
+# RenderLayer
+
+`RenderLayer` decouples render order from the scene graph hierarchy. Objects keep their logical parent (for transforms) but render at the layer's position in the scene. Use layers to pull specific objects to a specific z-depth without reparenting; the classic "character is parented to the world, but draws on the UI overlay" problem.
+
+## Quick Start
+
+```ts
+const bgLayer = new RenderLayer();
+const entityLayer = new RenderLayer();
+const uiLayer = new RenderLayer();
+
+app.stage.addChild(bgLayer, entityLayer, uiLayer);
+
+const world = new Container();
+app.stage.addChild(world);
+
+const player = new Sprite(texture);
+world.addChild(player); // logical parent for transforms
+entityLayer.attach(player); // render position
+```
+
+The player lives in `world` for transform purposes (so moving the world moves the player), but the renderer draws it in the order determined by `entityLayer`'s position in the stage.
+
+## Core Patterns
+
+### attach / detach
+
+```ts
+layer.attach(sprite);
+layer.attach(sprite1, sprite2, sprite3);
+
+layer.detach(sprite);
+layer.detachAll();
+```
+
+Use `attach()` / `detach()` for layer membership; not `addChild` / `removeChild`. RenderLayer overrides the scene graph methods to throw errors.
+
+### Sorted layers
+
+```ts
+const sortedLayer = new RenderLayer({
+  sortableChildren: true,
+  sortFunction: (a, b) => a.position.y - b.position.y,
+});
+
+sortedLayer.attach(sprite1, sprite2, sprite3);
+```
+
+Set `sortableChildren: true` on the layer (not the object) and optionally pass a custom `sortFunction`. The default sort is by `zIndex`. Common use: y-sort for 2D top-down games so objects draw in depth order based on world y-position.
+
+### Manual sort
+
+```ts
+const layer = new RenderLayer({ sortableChildren: false });
+layer.attach(sprite1, sprite2, sprite3);
+
+layer.sortRenderLayerChildren();
+```
+
+If you turn off automatic sorting, call `sortRenderLayerChildren()` manually when you want the sort to happen. Useful when the sort order changes less often than every frame.
+
+### Layer + logical parent
+
+```ts
+const world = new Container();
+const hud = new RenderLayer();
+app.stage.addChild(world, hud);
+
+const player = new Sprite(playerTexture);
+world.addChild(player);
+hud.attach(player);
+
+world.x = 100; // player still moves with world
+```
+
+The player's transform chain goes through `world`; moving `world.x` moves the player visually. But the renderer places the player's draw call at `hud`'s position in the scene graph, so the player renders on top of everything else.
+
+### Removing from scene graph auto-detaches
+
+```ts
+world.removeChild(player);
+// player is automatically detached from entityLayer
+```
+
+When you remove an object from its scene graph parent (via `removeChild`), the render layer attachment is cleared automatically. Re-adding the object to a scene graph parent does NOT re-attach it; you must call `layer.attach(player)` again.
+
+## Common Mistakes
+
+### [CRITICAL] Using `addChild` on a RenderLayer
+
+Wrong:
+
+```ts
+const layer = new RenderLayer();
+layer.addChild(sprite);
+```
+
+Correct:
+
+```ts
+const layer = new RenderLayer();
+container.addChild(sprite);
+layer.attach(sprite);
+```
+
+`RenderLayer` throws on `addChild`. The object still needs a real scene graph parent (via `addChild` on a Container) for transforms; use `layer.attach()` to control render order.
+
+
+### [HIGH] Layer and attached children in different render groups
+
+Wrong:
+
+```ts
+const renderGroup = new Container({ isRenderGroup: true });
+const layer = new RenderLayer();
+
+renderGroup.addChild(sprite);
+app.stage.addChild(layer);
+layer.attach(sprite);
+```
+
+Correct:
+
+```ts
+const renderGroup = new Container({ isRenderGroup: true });
+const layer = new RenderLayer();
+
+renderGroup.addChild(sprite);
+renderGroup.addChild(layer);
+layer.attach(sprite);
+```
+
+A layer and the objects it attaches must be in the same render group. Otherwise the attached child renders without its correct transform composition.
+
+
+### [MEDIUM] Expecting parent filters to apply to layer children
+
+Filters on an ancestor Container are applied by capturing the container's children into a texture via push/pop. Layer-attached children skip this capture; they're collected separately and drawn at the layer's position. If you need a filter on a layer-attached object, apply the filter directly to the object (not the ancestor).
+
+
+## API Reference
+
+- [RenderLayer](https://pixijs.download/release/docs/scene.RenderLayer.html.md)
+- [RenderLayerOptions](https://pixijs.download/release/docs/scene.RenderLayerOptions.html.md)
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/masking.md

@@ -0,0 +1,129 @@
+# Masking
+
+Clip display objects with PixiJS masks. PixiJS supports four mask types: AlphaMask (sprite-based), StencilMask (Graphics/Container-based via the stencil buffer), ScissorMask (axis-aligned rectangle), and ColorMask (bit-mask on channels).
+
+## Quick Start
+
+```ts
+const photoGroup = new Container();
+photoGroup.addChild(new Sprite(await Assets.load("photo.png")));
+
+const mask = new Graphics().circle(100, 100, 80).fill(0xffffff);
+photoGroup.mask = mask;
+photoGroup.addChild(mask);
+
+app.stage.addChild(photoGroup);
+```
+
+A mask should live in the scene graph of the masked object's parent (typically as a child of the masked Container) so its transform tracks the masked subtree. Sprites, Text, and other leaves cannot hold the mask as a child (`allowChildren = false`); wrap them in a `Container` as shown above.
+
+Set `container.mask` to a display object. PixiJS automatically selects the mask type based on what you assign.
+
+## Core Patterns
+
+### Mask type selection
+
+PixiJS picks the mask type automatically based on the mask object:
+
+| Mask object           | Type used   | Cost      | Notes                           |
+| --------------------- | ----------- | --------- | ------------------------------- |
+| Graphics or Container | StencilMask | Medium    | Uses stencil buffer             |
+| Sprite                | AlphaMask   | Expensive | Uses filter pipeline internally |
+| Number (e.g., `0xF`)  | ColorMask   | Cheapest  | Bitmask on RGBA channels        |
+
+Performance hierarchy: ColorMask (cheapest) < StencilMask < AlphaMask (most expensive). Choose the simplest mask that achieves the visual result.
+
+Note: `ScissorMask` exists in the codebase but is not auto-selected by the mask system. Only `AlphaMask`, `StencilMask`, and `ColorMask` are registered as mask effects.
+
+### Stencil mask (Graphics-based)
+
+```ts
+const container = new Container();
+const mask = new Graphics().roundRect(0, 0, 200, 150, 20).fill(0xffffff);
+
+container.mask = mask;
+container.addChild(mask);
+```
+
+The mask Graphics should be a child of the masked container (or share the same coordinate space). The fill color doesn't matter; only the shape is used.
+
+### Alpha mask (Sprite-based)
+
+```ts
+const maskTexture = await Assets.load("gradient-mask.png");
+const maskSprite = new Sprite(maskTexture);
+
+const photoGroup = new Container();
+photoGroup.addChild(new Sprite(await Assets.load("photo.png")));
+photoGroup.mask = maskSprite;
+photoGroup.addChild(maskSprite);
+```
+
+Alpha masks use the **red channel** of the sprite texture by default to control visibility. High red value = fully visible, zero red = hidden. This is the most expensive mask type because it uses the filter pipeline internally.
+
+### Mask channel selection
+
+By default, sprite (alpha) masks read the red channel. If your mask texture uses transparency instead (e.g., a PNG with an alpha gradient), switch to the alpha channel via `setMask`:
+
+```ts
+const maskSprite = new Sprite(await Assets.load("alpha-gradient.png"));
+
+const photoGroup = new Container();
+photoGroup.addChild(new Sprite(await Assets.load("photo.png")));
+photoGroup.setMask({ mask: maskSprite, channel: "alpha" });
+photoGroup.addChild(maskSprite);
+```
+
+Available channels: `'red'` (default), `'alpha'`. This is useful when a single mask texture encodes different shapes in different channels.
+
+### Inverse masking
+
+Use `setMask` with `inverse: true` to show everything outside the mask shape:
+
+```ts
+const holeMask = new Graphics().circle(100, 100, 80).fill(0xffffff);
+const container = new Container();
+container.setMask({ mask: holeMask, inverse: true });
+container.addChild(holeMask);
+
+const maskSprite = new Sprite(await Assets.load("mask.png"));
+const photoGroup = new Container();
+photoGroup.addChild(new Sprite(await Assets.load("photo.png")));
+photoGroup.setMask({ mask: maskSprite, inverse: true });
+photoGroup.addChild(maskSprite);
+```
+
+Both alpha and stencil masks support inverse on WebGL and WebGPU. Canvas2D does not support inverse stencil masks (it logs a warning and ignores the flag).
+
+### Removing a mask
+
+```ts
+container.mask = null;
+mask.destroy();
+
+// Sprite masks: clear the mask before destroying its texture
+photoGroup.mask = null;
+maskSprite.destroy({ texture: true, textureSource: true });
+```
+
+Always use `container.mask = null` to clear a mask. `setMask({ mask: null })` does not work due to an internal falsy check. Remove the mask reference before destroying the mask, the masked object, or (for sprite masks) the mask's texture. A sprite mask whose texture is destroyed while still assigned renders as empty and, in debug builds, logs `[MaskFilter] The mask texture was destroyed while the mask is still in use. Remove the mask before destroying its texture.`
+
+## Common Mistakes
+
+### [HIGH] Using cacheAsTexture with masks
+
+The combination of `cacheAsTexture()` and masks is fragile. In Firefox, it can require a timeout between setting the mask and enabling caching. In other cases it fails silently. Avoid combining them when possible, or test thoroughly across browsers if needed.
+
+### [MEDIUM] Using too many sprite masks
+
+Sprite masks (AlphaMask) use the filter pipeline internally, making them the most expensive mask type. Using many of them simultaneously degrades performance significantly. Prefer stencil masks (Graphics shapes) or scissor masks (axis-aligned rectangles) when the visual result allows it.
+
+Performance cost: Scissor (near zero) < Stencil (one extra draw) < Alpha (full filter pass)
+
+## API Reference
+
+- [AlphaMask](https://pixijs.download/release/docs/rendering.AlphaMask.html.md)
+- [StencilMask](https://pixijs.download/release/docs/rendering.StencilMask.html.md)
+- [ScissorMask](https://pixijs.download/release/docs/rendering.ScissorMask.html.md)
+- [ColorMask](https://pixijs.download/release/docs/rendering.ColorMask.html.md)
+- [MaskEffectManager](https://pixijs.download/release/docs/rendering.MaskEffectManager.html.md)