@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-scene-dom-container/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: pixijs-scene-dom-container
+description: "Use this skill when overlaying HTML elements on the PixiJS v8 canvas. Covers DOMContainer with element, anchor, and scene-graph-driven CSS transforms, the pixi.js/dom side-effect import, DOMPipe registration, visibility sync, pointer-events handling. Triggers on: DOMContainer, pixi.js/dom, DOMPipe, HTML overlay, input on canvas, iframe overlay, DOMContainerOptions, element, anchor, constructor options."
+license: MIT
+---
+
+`DOMContainer` positions an HTML element over the PixiJS canvas and drives its CSS transform from the scene graph. Use it for native inputs, iframes, videos, or rich HTML that needs to follow a display object's position. The default `pixi.js` browser bundle registers the `DOMPipe` automatically; custom builds add a side-effect `import 'pixi.js/dom'`.
+
+> `DOMContainer` is marked EXPERIMENTAL in PixiJS v8. The API may change between minor releases.
+
+Assumes familiarity with `pixijs-scene-core-concepts`. `DOMContainer` extends `ViewContainer`, so it's a leaf: do not nest PixiJS children inside it. Nest DOM content inside the HTML element itself, or wrap multiple `DOMContainer` instances in a `Container`. Not available in Web Workers; a worker has no DOM to overlay.
+
+## Quick Start
+
+```ts
+import "pixi.js/dom";
+
+const input = document.createElement("input");
+input.type = "text";
+input.placeholder = "Enter name...";
+
+const dom = new DOMContainer({
+  element: input,
+  anchor: 0.5,
+});
+dom.position.set(app.screen.width / 2, app.screen.height / 2);
+
+app.stage.addChild(dom);
+```
+
+**Related skills:** `pixijs-scene-core-concepts` (scene graph basics), `pixijs-scene-container` (wrap multiple DOM overlays), `pixijs-events` (pointer handling on canvas vs DOM), `pixijs-accessibility` (screen-reader overlays).
+
+## Constructor options
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+Leaf-specific options added by `DOMContainerOptions`:
+
+| Option    | Type                  | Default                         | Description                                                                                                                                                                    |
+| --------- | --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `element` | `HTMLElement`         | `document.createElement('div')` | The HTML element the container drives. Any element is valid: `input`, `textarea`, `iframe`, `video`, `div`, etc. If omitted, a bare `<div>` is created.                        |
+| `anchor`  | `PointData \| number` | `0`                             | Origin of the element relative to its own dimensions. `0` is top-left, `0.5` centers, `1` is bottom-right. A single number sets both axes; `{ x, y }` sets each independently. |
+
+`tint`, `filters`, `mask`, and `blendMode` are accepted (inherited from `Container`) but have no visual effect — DOM elements live outside the WebGL/WebGPU pipeline. Style the element via CSS for those effects.
+
+## Core Patterns
+
+### Setup and the side-effect import
+
+```ts
+import "pixi.js/dom";
+import { DOMContainer } from "pixi.js";
+```
+
+Or use the combined import that registers the pipe and re-exports the class:
+
+```ts
+import { DOMContainer } from "pixi.js/dom";
+```
+
+The default `pixi.js` browser bundle already imports `pixi.js/dom` for you via `browserAll.ts`, so `DOMContainer` works out of the box in a typical browser app. You only need the explicit `import 'pixi.js/dom'` line when you set `skipExtensionImports: true` (custom builds) or when running under a non-browser bundle.
+
+### Transforms, anchor, and alpha
+
+```ts
+const dom = new DOMContainer({
+  element: document.createElement("div"),
+  anchor: 0.5,
+});
+dom.position.set(400, 300);
+dom.scale.set(1.5);
+dom.rotation = Math.PI / 8;
+dom.alpha = 0.5;
+```
+
+Transforms on the `DOMContainer` propagate to the element as CSS `transform`. `anchor` shifts the element's origin relative to its own dimensions: `0` is top-left, `0.5` centers, `1` is bottom-right. A single number sets both axes; an object `{ x, y }` sets each independently. `alpha` (including inherited parent alpha) is written to the element's `style.opacity` every frame.
+
+If no `element` is provided, a `<div>` is created by default.
+
+### Styling the element directly
+
+```ts
+const panel = document.createElement("div");
+panel.innerHTML = "<h2>Score</h2><p>1500</p>";
+panel.style.color = "white";
+panel.style.fontFamily = "Arial";
+panel.style.pointerEvents = "none";
+
+const dom = new DOMContainer({ element: panel });
+dom.position.set(50, 50);
+app.stage.addChild(dom);
+```
+
+PixiJS does not interfere with CSS styling on the element. The shared root `<div>` is set to `pointer-events: none`, and each attached element defaults to `pointer-events: auto`. Override to `none` on purely decorative overlays so the canvas still receives clicks underneath them.
+
+### Visibility and cleanup
+
+```ts
+dom.visible = false;
+dom.visible = true;
+
+dom.destroy();
+```
+
+Setting `visible = false` or removing the `DOMContainer` from the scene graph detaches the element from the DOM. Restoring visibility re-attaches it. `destroy()` removes the element from its parent node and nulls internal references; the HTML element itself is preserved, so you can re-attach it elsewhere:
+
+```ts
+const element = dom.element;
+dom.destroy();
+document.body.appendChild(element);
+```
+
+### The DOM container root
+
+The DOMPipe uses a shared root `<div>` with `z-index: 1000` that hosts every attached element. It's exposed as `app.domContainerRoot` (an `HTMLDivElement`). All `DOMContainer` elements render above canvas content; you can't interleave DOM elements between PixiJS draw calls.
+
+On the first render that has an attached `DOMContainer`, the pipe automatically appends the root to the canvas's parent node. Append it yourself next to `app.canvas` if you need explicit, stable placement in the DOM tree (for example, when the canvas shares a wrapper with other layered content):
+
+```ts
+document.body.appendChild(app.canvas);
+document.body.appendChild(app.domContainerRoot);
+```
+
+The root uses absolute positioning and its transform is recomputed from the canvas `getBoundingClientRect()` via a `ResizeObserver`, so CSS-scaled canvases stay aligned without extra work.
+
+## Common Mistakes
+
+### [MEDIUM] Missing the pixi.js/dom import in custom builds
+
+The default browser bundle auto-registers `DOMPipe`, so most apps do not need an explicit import. It is only required when you opt out of auto-imports:
+
+```ts
+await app.init({ skipExtensionImports: true });
+// Now you must add this yourself:
+import "pixi.js/dom";
+```
+
+Without registration under a custom build, `DOMContainer` is still importable but the renderer has no pipe to process it; elements never synchronize with the scene graph and never appear.
+
+
+### [MEDIUM] Expecting filters, masks, or blend modes to affect DOM elements
+
+Wrong:
+
+```ts
+const dom = new DOMContainer();
+dom.filters = [new BlurFilter()];
+```
+
+Correct:
+
+```ts
+dom.element.style.filter = "blur(4px)";
+```
+
+DOM elements are HTML overlays positioned via CSS transforms; they exist outside the WebGL/WebGPU pipeline. PixiJS filters, masks, and blend modes have no effect on them. Use CSS filters and CSS `mix-blend-mode` on the element directly.
+
+
+### [MEDIUM] Do not nest children inside a DOMContainer
+
+Wrong:
+
+```ts
+const dom = new DOMContainer();
+dom.addChild(new Sprite(texture));
+```
+
+Correct:
+
+```ts
+const group = new Container();
+group.addChild(dom, new Sprite(texture));
+```
+
+`DOMContainer` extends `ViewContainer`, which sets `allowChildren = false`. It is a leaf in the PixiJS scene graph. For PixiJS children, wrap the `DOMContainer` alongside them in a plain `Container`. For nested HTML, nest inside the element itself (`element.appendChild(...)`).
+
+
+### [LOW] Forgetting to set anchor for centered positioning
+
+The default anchor is `(0, 0)`, placing the element's top-left corner at the container's position. For centering a UI element on its scene-graph position, set `anchor: 0.5`:
+
+```ts
+const dom = new DOMContainer({ element: myElement, anchor: 0.5 });
+dom.position.set(400, 300);
+```
+
+
+## API Reference
+
+- [DOMContainer](https://pixijs.download/release/docs/scene.DOMContainer.html.md)
+- [DOMContainerOptions](https://pixijs.download/release/docs/scene.DOMContainerOptions.html.md)
+- [ViewContainer](https://pixijs.download/release/docs/scene.ViewContainer.html.md)
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-gif/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: pixijs-scene-gif
+description: "Use this skill when displaying animated GIFs in PixiJS v8. Covers the pixi.js/gif side-effect import, Assets.load returning a GifSource, GifSprite playback (play/stop/currentFrame/animationSpeed), autoPlay/loop options, onComplete/onLoop/onFrameChange callbacks, GifSource sharing, clone, destroy. Triggers on: GifSprite, GifSource, pixi.js/gif, animationSpeed, currentFrame, autoPlay, onComplete, onFrameChange, constructor options, GifSpriteOptions."
+license: MIT
+---
+
+`GifSprite` plays an animated GIF as a display object. `Assets.load('animation.gif')` returns a `GifSource` (not a `Texture`), and you wrap that in a `GifSprite`. Requires a side-effect `import 'pixi.js/gif'` to register the loader extension.
+
+Assumes familiarity with `pixijs-scene-core-concepts`. `GifSprite` extends `Sprite`, so it is a leaf: do not nest children inside it. Wrap multiple `GifSprite` instances in a `Container` to group them.
+
+## Quick Start
+
+```ts
+import "pixi.js/gif";
+import { GifSprite } from "pixi.js/gif";
+
+const source = await Assets.load("animation.gif");
+
+const gif = new GifSprite({
+  source,
+  autoPlay: true,
+  loop: true,
+  animationSpeed: 1,
+});
+
+gif.anchor.set(0.5);
+gif.x = app.screen.width / 2;
+gif.y = app.screen.height / 2;
+
+app.stage.addChild(gif);
+```
+
+> [!NOTE]
+> GIFs decode every frame into a separate canvas texture. For performance-critical animations with many frames, prefer a spritesheet with `AnimatedSprite` — it uses a single atlas texture and batches better on the GPU.
+
+**Related skills:** `pixijs-scene-core-concepts` (scene graph basics), `pixijs-scene-sprite` (`AnimatedSprite` for spritesheet-based animation), `pixijs-assets` (`Assets.load`, caching, unloading), `pixijs-ticker` (frame timing), `pixijs-performance` (texture memory).
+
+## Constructor options
+
+`GifSpriteOptions` extends `Omit<SpriteOptions, 'texture'>`; `texture` is managed internally (set from `source.textures[0]` and swapped per frame). All other `Sprite` options (`anchor`, `scale`, `tint`, `roundPixels`, etc.) are valid, and all `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+Leaf-specific options added by `GifSpriteOptions`:
+
+| Option           | Type                              | Default    | Description                                                                                                                |
+| ---------------- | --------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `source`         | `GifSource`                       | —          | Required. The parsed GIF data returned by `Assets.load('file.gif')`. Can be shared across multiple `GifSprite` instances.  |
+| `autoPlay`       | `boolean`                         | `true`     | Start playback immediately on construction. If `false`, you must call `gif.play()` to begin.                               |
+| `loop`           | `boolean`                         | `true`     | Repeat the animation on reaching the last frame. When `false`, the sprite stops at the final frame and fires `onComplete`. |
+| `animationSpeed` | `number`                          | `1`        | Multiplier on the GIF's native frame timing. `2` runs at double speed; `0.5` runs at half.                                 |
+| `autoUpdate`     | `boolean`                         | `true`     | Connect playback to `Ticker.shared`. Set to `false` to drive updates yourself via `gif.update(ticker)`.                    |
+| `fps`            | `number`                          | `30`       | Fallback frame rate for GIFs that do not specify per-frame delays.                                                         |
+| `onComplete`     | `() => void \| null`              | `null`     | Called when a non-looping animation reaches the last frame.                                                                |
+| `onLoop`         | `() => void \| null`              | `null`     | Called each time a looping animation wraps around.                                                                         |
+| `onFrameChange`  | `(frame: number) => void \| null` | `null`     | Called every time the displayed frame index changes.                                                                       |
+| `scaleMode`      | `SCALE_MODE`                      | `'linear'` | Deprecated since 8.13.0 — pass `scaleMode` via `Assets.load(..., { data: { scaleMode } })` instead.                        |
+
+The constructor also accepts a bare `GifSource` as its sole argument (`new GifSprite(source)`), which is shorthand for `new GifSprite({ source })` using the defaults above.
+
+## Core Patterns
+
+### Setup and the side-effect import
+
+```ts
+import "pixi.js/gif";
+import { Assets } from "pixi.js";
+import { GifSprite } from "pixi.js/gif";
+
+const source = await Assets.load("animation.gif");
+const gif = new GifSprite({ source });
+```
+
+`pixi.js/gif` calls `extensions.add(GifAsset)`, registering `.gif` with the asset loader. Without it, `Assets.load` does not recognize GIF files. `GifSprite` and `GifSource` are exported from `pixi.js/gif`, not `pixi.js`.
+
+Importing a named export from `pixi.js/gif` also triggers the side effect, so a bare `import 'pixi.js/gif'` is only needed when you don't import anything from that path.
+
+### Playback control
+
+```ts
+const gif = new GifSprite({ source });
+
+gif.play();
+gif.stop();
+
+gif.currentFrame = 5;
+gif.animationSpeed = 2;
+gif.animationSpeed = 0.5;
+
+gif.playing; // read-only
+gif.progress; // 0-1 playback position
+gif.totalFrames; // number of frames
+gif.duration; // total duration in ms
+```
+
+`autoPlay: true` (default) starts playback immediately; `loop: true` (default) repeats. `animationSpeed` is a multiplier on the GIF's native frame timing. `currentFrame` is zero-based.
+
+### Loading options
+
+```ts
+const source = await Assets.load({
+  src: "animation.gif",
+  data: {
+    fps: 12,
+    scaleMode: "nearest",
+    resolution: 2,
+  },
+});
+
+const fromDataUri = await Assets.load("data:image/gif;base64,R0lGODlh...");
+```
+
+Options in `data` are passed to `GifSource.from`. `fps` sets the fallback frame delay for GIFs that don't specify timing. `scaleMode` and `resolution` control the canvas textures created for each frame. The loader matches both `.gif` file extensions and `data:image/gif` URIs.
+
+### Callbacks
+
+```ts
+const gif = new GifSprite({
+  source,
+  loop: false,
+  onComplete: () => console.log("animation finished"),
+  onLoop: () => console.log("loop completed"),
+  onFrameChange: (frame) => console.log("now on frame", frame),
+});
+```
+
+- `onComplete` fires when a non-looping animation reaches the last frame.
+- `onLoop` fires each time a looping animation wraps around.
+- `onFrameChange` fires every time the displayed frame changes.
+
+### Manual update mode
+
+```ts
+const gif = new GifSprite({ source, autoUpdate: false });
+
+app.ticker.add((ticker) => {
+  gif.update(ticker);
+});
+```
+
+`autoUpdate: false` disconnects from `Ticker.shared`. You call `gif.update(ticker)` yourself, passing any `Ticker` instance. Useful when animation should be driven by a private ticker (e.g., a pause-aware game ticker).
+
+### Sharing source data and cloning
+
+```ts
+const source = await Assets.load("animation.gif");
+
+const gif1 = new GifSprite({ source, autoPlay: true });
+const gif2 = new GifSprite({ source, autoPlay: false });
+
+const gif3 = gif1.clone();
+gif3.animationSpeed = 0.5;
+```
+
+`GifSource` can be shared across multiple `GifSprite` instances; each sprite has independent playback state. `clone()` copies all playback settings but creates an independent instance.
+
+## Common Mistakes
+
+### [HIGH] Not importing pixi.js/gif
+
+Wrong:
+
+```ts
+import { Assets } from "pixi.js";
+const gif = await Assets.load("animation.gif");
+```
+
+Correct:
+
+```ts
+import "pixi.js/gif";
+import { Assets } from "pixi.js";
+const source = await Assets.load("animation.gif");
+```
+
+The GIF loader extension must be registered before loading. Without the side-effect import, the loader does not recognize `.gif` files and the load either fails or returns raw data.
+
+
+### [MEDIUM] Expecting Assets.load to return a Texture
+
+Wrong:
+
+```ts
+const texture = await Assets.load("animation.gif");
+const sprite = new Sprite(texture);
+```
+
+Correct:
+
+```ts
+const source = await Assets.load("animation.gif");
+const gif = new GifSprite({ source });
+```
+
+`Assets.load` on a GIF returns a `GifSource` containing frame textures and timing data. Pass the source to `GifSprite`; for a single still frame, read `source.textures[0]`.
+
+
+### [MEDIUM] GIF memory not released on destroy
+
+Wrong:
+
+```ts
+gif.destroy();
+// GifSource and frame textures remain in memory
+```
+
+Correct:
+
+```ts
+gif.destroy(true);
+// or
+await Assets.unload("animation.gif");
+```
+
+GIF frames hold decoded pixel data as individual canvas textures. `gif.destroy()` (or `destroy(false)`) destroys the sprite but keeps the `GifSource` intact. Pass `true` to also destroy the source. For shared sources, only destroy when the last consumer is done, or call `Assets.unload` to let the asset cache handle it.
+
+
+### [LOW] Do not nest children inside a GifSprite
+
+`GifSprite` extends `Sprite`, which sets `allowChildren = false`. It is a leaf. To group a GIF with other display objects, wrap them all in a plain `Container`:
+
+```ts
+const group = new Container();
+group.addChild(gif, label);
+```
+
+
+## API Reference
+
+- [GifSprite](https://pixijs.download/release/docs/gif.GifSprite.html.md)
+- [GifSpriteOptions](https://pixijs.download/release/docs/gif.GifSpriteOptions.html.md)
+- [GifSource](https://pixijs.download/release/docs/gif.GifSource.html.md)
+- [GifAsset](https://pixijs.download/release/docs/gif.GifAsset.html.md)
+- [GifBufferOptions](https://pixijs.download/release/docs/gif.GifBufferOptions.html.md)
+- [GifFrame](https://pixijs.download/release/docs/gif.GifFrame.html.md)