@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-scene-text/references/split-text.md

@@ -0,0 +1,168 @@
+# SplitText
+
+A container that splits a canvas `Text` render into independently-animatable `lines`, `words`, and `chars`; each exposed as its own `Text` instance. Use `SplitText` for per-character intro animations, staggered reveals, or any effect where you need to transform each glyph, word, or line separately.
+
+## Quick Start
+
+```ts
+const split = new SplitText({
+  text: "Animate Me",
+  style: { fontSize: 48, fill: 0xffffff },
+  charAnchor: { x: 0.5, y: 1 },
+});
+
+app.stage.addChild(split);
+
+split.chars.forEach((char, i) => {
+  char.alpha = 0;
+  char.y = -40;
+  const delay = i * 80;
+  setTimeout(() => {
+    app.ticker.add(() => {
+      char.alpha = Math.min(char.alpha + 0.05, 1);
+      char.y += (0 - char.y) * 0.1;
+    });
+  }, delay);
+});
+```
+
+`SplitText` is new in v8; API shape may still evolve. It wraps `Text` internally, so the same TextStyle options apply. Every character is a full `Text` instance; use sparingly and prefer `SplitBitmapText` for long strings or many animated instances.
+
+## Construction
+
+```ts
+const minimal = new SplitText({
+  text: "Hello World",
+  style: { fontSize: 32, fill: 0xffffff },
+});
+
+const full = new SplitText({
+  text: "Animate\nEvery Character",
+  style: { fontSize: 48, fill: "white", stroke: { color: "black", width: 2 } },
+  autoSplit: true,
+  lineAnchor: 0.5,
+  wordAnchor: { x: 0, y: 0.5 },
+  charAnchor: { x: 0.5, y: 1 },
+  x: 100,
+  y: 200,
+  alpha: 0.8,
+});
+```
+
+### SplitTextOptions
+
+`SplitText` is a `Container` (not a `ViewContainer`), so unlike `Text` it does NOT take `anchor`, `resolution`, `roundPixels`, `textureStyle`, or `autoGenerateMipmaps` at the top level. Those belong on the internal per-character `Text` instances. The splitting behavior is controlled by the fields below.
+
+| Option       | Type                                     | Default | Description                                                                                                            |
+| ------------ | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `text`       | `string`                                 | —       | Text content to render and segment. Required.                                                                          |
+| `style`      | `TextStyle \| Partial<TextStyleOptions>` | —       | TextStyle instance or style options; the same TextStyle used by `Text`. See `references/text.md`. Required.            |
+| `autoSplit`  | `boolean`                                | `true`  | Automatically re-split when `text` or `style` changes; set `false` to batch updates and call `split.split()` manually. |
+| `lineAnchor` | `number \| PointData`                    | `0`     | Normalized transform origin (0–1) for each line container; controls the pivot of per-line rotations/scales.            |
+| `wordAnchor` | `number \| PointData`                    | `0`     | Same as `lineAnchor` but for each word container.                                                                      |
+| `charAnchor` | `number \| PointData`                    | `0`     | Same as `lineAnchor` but for each character container.                                                                 |
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+> `SplitText.defaultOptions` overrides the defaults globally for every new `SplitText` instance. The built-in defaults are the values above.
+
+## Core Patterns
+
+### Segment access
+
+```ts
+split.lines.forEach((line) => {
+  line.alpha = 0.8;
+});
+split.words.forEach((word) => {
+  word.rotation = 0.1;
+});
+split.chars.forEach((char) => {
+  char.scale.set(1.2);
+});
+```
+
+`lines` and `words` are `Container[]`; `chars` is `Text[]` directly (or `BitmapText[]` for `SplitBitmapText`). All three arrays are refreshed whenever the text or style changes (when `autoSplit` is `true`).
+
+### Transform origins
+
+```ts
+const split = new SplitText({
+  text: "Wave",
+  style: { fontSize: 64, fill: 0xffffff },
+  lineAnchor: 0.5,
+  wordAnchor: { x: 0, y: 0.5 },
+  charAnchor: { x: 0.5, y: 1 },
+});
+```
+
+- `lineAnchor`: transform origin for each line container (0–1 normalized).
+- `wordAnchor`: transform origin for each word container.
+- `charAnchor`: transform origin for each character container.
+
+Setting these once at construction time ensures rotations and scales pivot around the intended point (center, bottom, etc.).
+
+### Animating per character
+
+```ts
+split.chars.forEach((char, i) => {
+  char.onRender = () => {
+    const t = performance.now() / 200 + i;
+    char.y = Math.sin(t) * 5;
+  };
+});
+```
+
+Using each character's `onRender` hook avoids one global ticker callback. Each char updates itself every render pass.
+
+### Auto-split on change
+
+```ts
+split.text = "New text";
+```
+
+With `autoSplit = true` (default), reassigning `text` or `style` re-splits and rebuilds the segment arrays. Set `autoSplit = false` to batch multiple changes before calling `split.split()` manually (see `pixijs-scene-text` source).
+
+### Constructing from an existing Text
+
+```ts
+const plain = new Text({ text: "Convert me", style: { fontSize: 32 } });
+const converted = SplitText.from(plain);
+```
+
+`SplitText.from(existingText)` copies content and style, then splits. Useful when you already have a `Text` instance and want to apply per-character animation retroactively.
+
+## Common Mistakes
+
+### [HIGH] Many SplitText instances with long strings
+
+Each character is a full `Text` instance with its own canvas rasterization and GPU texture. A 40-character `SplitText` creates 40 text renders at construction time. For long strings, use `SplitBitmapText`; it wraps `BitmapText` instead, so each character reuses the glyph atlas.
+
+
+### [MEDIUM] Modifying `chars` array directly
+
+Wrong:
+
+```ts
+split.chars.push(extraChar);
+```
+
+Correct:
+
+```ts
+split.text = split.text + "extra";
+```
+
+`chars`, `words`, and `lines` are managed arrays. Pushing to them is ignored and will be overwritten on the next auto-split. Always update via the `text` property and let the class rebuild segments.
+
+
+### [MEDIUM] Expecting segments before the first render
+
+When `autoSplit` is true, splitting happens lazily on first property read or render. If you need segments immediately after construction, access `chars` (or call `split.split()` manually) once before iterating.
+
+
+## API Reference
+
+- [SplitText](https://pixijs.download/release/docs/text.SplitText.html.md)
+- [AbstractSplitText](https://pixijs.download/release/docs/text.AbstractSplitText.html.md)
+- [SplitTextOptions](https://pixijs.download/release/docs/text.SplitTextOptions.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-text/references/text.md

@@ -0,0 +1,311 @@
+# Text (Canvas Text)
+
+The primary text renderer in PixiJS v8. Rasterizes strings to an off-screen canvas via the native Canvas API, then uploads the result as a GPU texture. Use `Text` for high-quality typography, styled labels, UI text, and anything where visual fidelity matters more than update speed. For frequently-changing numeric displays (scores, timers), prefer `BitmapText`.
+
+## Quick Start
+
+```ts
+const text = new Text({
+  text: "Hello PixiJS",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 36,
+    fill: 0xffffff,
+    stroke: { color: "#4a1850", width: 5 },
+    dropShadow: {
+      color: "#000000",
+      blur: 4,
+      distance: 6,
+      angle: Math.PI / 6,
+    },
+  },
+  anchor: 0.5,
+  x: 400,
+  y: 40,
+});
+
+app.stage.addChild(text);
+```
+
+Text is a leaf (`allowChildren = false`). It uses an options-object constructor; positional `(string, style)` arguments from v7 are no longer supported.
+
+## Construction
+
+```ts
+const minimal = new Text({ text: "Hello" });
+
+const styled = new Text({
+  text: "Styled Text",
+  style: { fontSize: 24, fill: 0xff1010 },
+  anchor: 0.5,
+  resolution: 2,
+  roundPixels: true,
+});
+
+const crisp = new Text({
+  text: "Crisp Text",
+  style: { fontSize: 32 },
+  textureStyle: { scaleMode: "nearest" },
+  autoGenerateMipmaps: true,
+});
+```
+
+### CanvasTextOptions
+
+These are the options accepted by `new Text({ ... })`. The concrete `Text` constructor takes `CanvasTextOptions`, which extends the base `TextOptions` with the canvas-specific `textureStyle` and `autoGenerateMipmaps` fields.
+
+| Option                | Type                                                        | Default                                            | Description                                                                                                                                                               |
+| --------------------- | ----------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `text`                | `TextString` (`string \| number \| { toString(): string }`) | `''`                                               | Text content to display; `'\n'` inserts a line break.                                                                                                                     |
+| `style`               | `TextStyle \| TextStyleOptions`                             | `new TextStyle()`                                  | Text style object or options. See the existing TextStyle docs below for field details.                                                                                    |
+| `anchor`              | `PointData \| number`                                       | `0`                                                | Draw origin in `[0, 1]`; `0.5` is center, `1` is bottom-right.                                                                                                            |
+| `resolution`          | `number`                                                    | `null` (auto)                                      | Pixel density of the rasterized texture; `null` follows the renderer's resolution (setting to `null` at runtime enables auto-resolution; the interface type is `number`). |
+| `roundPixels`         | `boolean`                                                   | `false`                                            | Snap rendered x/y to whole pixels to avoid sub-pixel anti-aliasing.                                                                                                       |
+| `textureStyle`        | `TextureStyle \| TextureStyleOptions`                       | `undefined`                                        | Scale mode for the generated texture (`nearest` or `linear`); every other `TextureStyle` field is ignored. (@advanced)                                                    |
+| `autoGenerateMipmaps` | `boolean`                                                   | `TextureSource.defaultOptions.autoGenerateMipmaps` | Generate mipmaps for the text texture; improves quality when scaled down.                                                                                                 |
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+The `style` field is a rich nested type; the rest of this document covers its key properties.
+
+## Core Patterns
+
+### TextStyle properties
+
+```ts
+const styled = new Text({
+  text: "Styled",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 32,
+    fontWeight: "bold",
+    fontStyle: "italic",
+    fill: 0xff1010,
+    stroke: { color: "#4a1850", width: 5 },
+    dropShadow: {
+      color: "#000000",
+      blur: 4,
+      distance: 6,
+      angle: Math.PI / 6,
+      alpha: 0.8,
+    },
+    align: "center",
+    wordWrap: true,
+    wordWrapWidth: 300,
+    lineHeight: 45,
+    letterSpacing: 2,
+    padding: 4,
+  },
+});
+```
+
+Key TextStyle properties:
+
+- `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`
+- `fill`: color, gradient, or pattern (same `FillInput` as `Graphics`)
+- `stroke`: `{ color, width }` object
+- `dropShadow`: `{ color, blur, distance, angle, alpha }`
+- `wordWrap`, `wordWrapWidth`
+- `breakWords`: allow breaking mid-word when wrapping. Requires `wordWrap: true`
+- `whiteSpace`: `'normal' | 'pre' | 'pre-line'` whitespace handling for multi-line strings
+- `align`: `'left'`, `'center'`, `'right'`, `'justify'`; only affects multi-line text
+- `textBaseline`: `'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom'`
+- `lineHeight`, `letterSpacing`
+- `leading`: additional line spacing in pixels on top of `lineHeight`
+- `trim`: boolean; crop transparent padding after rasterization (expensive, use only when needed)
+- `padding`: extra space around the rendered texture; increase when a stroke or shadow gets clipped
+- `filters`: array of Pixi filters applied to the generated text texture at bake time, cheaper than filters on the `Text` node for static strings
+- `tagStyles`: per-tag inline style overrides
+
+### Tagged text
+
+```ts
+const alert = new Text({
+  text: "<red>Warning:</red> system <b>overloaded</b>",
+  style: {
+    fontSize: 24,
+    fill: 0xffffff,
+    tagStyles: {
+      red: { fill: 0xff0000 },
+      b: { fontWeight: "bold" },
+    },
+  },
+});
+```
+
+Tags are parsed only when `tagStyles` has entries; without entries, `<` is treated literally. Nested tags inherit from outer tags via an internal style stack.
+
+### Font loading
+
+```ts
+await Assets.load({
+  src: "my-font.woff2",
+  data: { family: "MyFont" },
+});
+
+const text = new Text({
+  text: "Custom Font",
+  style: { fontFamily: "MyFont", fontSize: 36, fill: 0xffffff },
+});
+```
+
+Supported formats: `woff2` (preferred), `woff`, `ttf`, `otf`. The `data` object is forwarded to `FontFace`; valid fields are `family`, `display`, `style`, `weights` (string array, e.g., `['normal', 'bold']`), `stretch`, `unicodeRange`, `featureSettings`, `variant`.
+
+```ts
+await Assets.load({
+  src: "titan-one.woff",
+  data: { family: "Titan One", weights: ["normal", "bold"] },
+});
+```
+
+### Resolution and mipmaps
+
+```ts
+const sharp = new Text({
+  text: "Crisp on retina",
+  style: { fontSize: 36, fill: 0xffffff },
+  resolution: 2,
+  autoGenerateMipmaps: true,
+});
+```
+
+- `resolution` (default: renderer's resolution): pixel density of the underlying texture. Higher values produce sharper text on high-DPI displays.
+- `autoGenerateMipmaps`: improves quality when the text is drawn smaller than its native size.
+
+### Dynamic content
+
+```ts
+app.ticker.add(() => {
+  const next = `Score: ${score}`;
+  if (scoreText.text !== next) {
+    scoreText.text = next;
+  }
+});
+```
+
+Guard text updates with an equality check when using `Text` for live values. Every assignment triggers a canvas re-render and GPU upload.
+
+### Sharing a TextStyle across instances
+
+```ts
+const style = new TextStyle({ fontSize: 24, fill: 0xffffff });
+
+const title = new Text({ text: "Title", style });
+const label = new BitmapText({ text: "Label", style });
+
+style.fill = 0xff0000; // both re-render
+
+title.destroy(); // detaches from `style`; `label` keeps using it
+```
+
+A `TextStyle` instance can be shared by any number of `Text`, `BitmapText`, and `HTMLText` objects; changing it re-renders all of them. `destroy()` detaches the text from the style without destroying it. Only pass `destroy({ style: true })` (or `destroy(true)`) when no other text object uses that style, since it destroys the shared instance.
+
+### Gradient and pattern fills
+
+```ts
+import { FillGradient } from "pixi.js";
+
+const gradient = new FillGradient({
+  end: { x: 0, y: 1 },
+  colorStops: [
+    { color: 0xff0000, offset: 0 },
+    { color: 0x0000ff, offset: 1 },
+  ],
+});
+
+const title = new Text({
+  text: "Gradient",
+  style: { fontSize: 64, fill: gradient },
+});
+```
+
+For a texture fill, pass a `FillPattern`. Its constructor takes an options object; the legacy positional form `new FillPattern(texture, repetition)` is also accepted.
+
+```ts
+import { Assets, FillPattern } from "pixi.js";
+
+const pattern = new FillPattern({
+  texture: await Assets.load("bricks.png"),
+  repetition: "repeat",
+});
+
+const label = new Text({
+  text: "PixiJS",
+  style: { fontSize: 64, fill: pattern },
+});
+```
+
+Canvas-rendered text ignores the pattern's `textureSpace`; the texture tiles in the text's pixel space at its native size. Use `pattern.setTransform(matrix)` to scale, rotate, or offset the tiles. A `FillPattern` works for `stroke` too, e.g. `style: { stroke: { fill: pattern, width: 10 } }`.
+
+`fill` accepts any `FillInput` that `Graphics` accepts; gradients, patterns, solid colors, and arrays of stops.
+
+## Common Mistakes
+
+### [HIGH] Updating Text content every frame
+
+Wrong:
+
+```ts
+app.ticker.add(() => {
+  scoreText.text = `Score: ${score}`;
+});
+```
+
+Correct:
+
+```ts
+const scoreText = new BitmapText({ text: "Score: 0", style });
+app.ticker.add(() => {
+  scoreText.text = `Score: ${score}`;
+});
+```
+
+Every `Text` update re-rasterizes the full string and uploads a new texture. At 60fps this burns frame budget. Use `BitmapText` for values that change per-frame, or at minimum guard with an equality check against the previous string.
+
+
+### [HIGH] Using positional constructor args
+
+Wrong:
+
+```ts
+const text = new Text("Hello", { fontSize: 24 });
+```
+
+Correct:
+
+```ts
+const text = new Text({ text: "Hello", style: { fontSize: 24 } });
+```
+
+v8 `Text` uses an options object. The v7 `(string, style)` signature is not supported.
+
+
+### [MEDIUM] Stroke or shadow getting clipped at edges
+
+Wrong:
+
+```ts
+const text = new Text({
+  text: "Hello",
+  style: { stroke: { color: "red", width: 10 } },
+});
+```
+
+Correct:
+
+```ts
+const text = new Text({
+  text: "Hello",
+  style: { stroke: { color: "red", width: 10 }, padding: 10 },
+});
+```
+
+The underlying canvas is sized from the text metrics; heavy strokes or drop-shadows render past those bounds and get clipped. Add `padding` to the style to enlarge the texture.
+
+
+## API Reference
+
+- [Text](https://pixijs.download/release/docs/scene.Text.html.md)
+- [TextStyle](https://pixijs.download/release/docs/text.TextStyle.html.md)
+- [TextOptions](https://pixijs.download/release/docs/text.TextOptions.html.md)
+- [AbstractText](https://pixijs.download/release/docs/scene.AbstractText.html.md)