aispritejs 0.1.2 → 0.1.3

package/README.md

@@ -19,6 +19,17 @@ Part of the **ai\*js** family: zero cross-package dependencies, framework-agnost
 - **Visual ≠ logic.** This is strictly a *visual* animator. It is **not** a game-logic FSM and does **not** depend on `aifsmjs`. Drive it from any logic layer (plain code, an FSM, an ECS) — they compose by convention, never by dependency.
 - **Tiny + fast.** O(1) input lookups, O(N) checks over transitions leaving the current state, no per-frame allocation.
 
+## When you DON'T need aispritejs
+
+`aispritejs` earns its keep when frame selection is **driven by runtime inputs** across **several visual states**. Below that threshold, reach for PixiJS directly — there is nothing to gain from a state machine:
+
+- **A single sprite / one static image** → a plain PixiJS [`Sprite`](https://pixijs.download/release/docs/scene.Sprite.html). No animation, no graph.
+- **One looping clip with no branching** (a coin spin, a torch flicker) → a PixiJS [`AnimatedSprite`](https://pixijs.download/release/docs/scene.AnimatedSprite.html) (`AnimatedSprite.fromFrames(...)`, `.play()`). One clip that always plays the same way needs no inputs.
+- **No texture atlas** (you aren't packing frames into a spritesheet) → load images directly; `aispritejs` reads its frames from a PixiJS-v8 atlas (`animations` / `frames`).
+- **No multi-state switching** — if your code already knows exactly which clip to play and just calls `.play()` / `.gotoAndStop()`, you don't need a transition graph.
+
+Reach for `aispritejs` when you have **input-driven, multi-state visual switching backed by a texture atlas** — e.g. `idle ⇄ walk → jump`, or a one-shot hit FX fired by a trigger — where which frame is on screen is a function of `speed` / `isGrounded` / `attack`, not a hard-coded `play()` call.
+
 ## Mental model
 
 ```
@@ -72,6 +83,50 @@ It swaps the texture only when the active frame changes, and honours per-frame `
 
 Pass a plain `Sprite` — the adapter owns frame selection. (An `AnimatedSprite` is accepted since it extends `Sprite`, but its own playback is stopped on bind so it cannot fight the adapter for the texture.)
 
+### Complete example — a 6-frame explosion (play-once FX)
+
+The most common entry: a one-shot hit/impact FX (net-splash, muzzle flash) from a **6-frame explosion sprite sheet**, driven through the `/pixi` adapter. A `Trigger` fires a **non-looping** clip that plays once and auto-returns to a resting frame via `onEnd`. The full runnable version is [`examples/02-explosion-pixi/index.ts`](examples/02-explosion-pixi/index.ts) (`pnpm example:explosion`).
+
+```ts
+import { Assets, Sprite } from "pixi.js";
+import { createPixiSpriteAnimator } from "aispritejs/pixi";
+
+// A 6-frame explosion sprite sheet (PixiJS-v8 atlas): the `animations` block
+// names the clip → its frame keys; `frames` carries per-frame durations.
+const graph = {
+  animations: {
+    explosion: ["explosion_0", "explosion_1", "explosion_2", "explosion_3", "explosion_4", "explosion_5"],
+    idle: ["explosion_0"], // a 1-frame resting clip to hold between bursts
+  },
+  frames: {
+    explosion_0: { duration: 40 }, explosion_1: { duration: 40 }, explosion_2: { duration: 40 },
+    explosion_3: { duration: 40 }, explosion_4: { duration: 40 }, explosion_5: { duration: 40 },
+  },
+  inputs: { detonate: { type: "trigger" } },
+  states: {
+    idle: { animation: "idle", loop: true },
+    boom: { animation: "explosion", loop: false, onEnd: "idle" }, // play once → back to idle
+  },
+  transitions: [
+    { from: "*", to: "boom", when: [{ input: "detonate", op: "Trigger" }], priority: 10 },
+  ],
+  initial: "idle",
+} as const;
+
+// Load the packed sheet; its `.textures` cover every frame key the graph uses.
+const sheet = await Assets.load("explosion.json"); // a PIXI.Spritesheet
+const sprite = new Sprite();
+const fx = createPixiSpriteAnimator(sprite, graph, sheet);
+
+// Fire the one-shot trigger on impact:
+fx.fireTrigger("detonate");
+
+// Drive the burst from your PixiJS render loop (e.g. `app.ticker`), advancing by
+// elapsed ms: `app.ticker.add((ticker) => fx.update(ticker.deltaMS))`.
+```
+
+`update(dt)` plays `explosion_0…explosion_5` once (honouring each frame's `duration`); on the tick that completes the clip it fires `onComplete` and, because `boom` declares `onEnd`, auto-transitions to `idle` in that **same** tick — so the last frame isn't held, and `activeState` reads `idle` right after. Re-`fireTrigger("detonate")` to replay. The same graph runs with no renderer — see [`examples/02-explosion-pixi/index.ts`](examples/02-explosion-pixi/index.ts), which exercises the real adapter headlessly with plain `Texture` / `Sprite` instances.
+
 ## Data format (atlas)
 
 `aispritejs` reads a **PixiJS v8-native** spritesheet atlas (`meta` / `frames` / `animations`) — the same shape the family's sprite pipeline emits — augmented with an `aispritejs` **input-driven** control block:
@@ -155,7 +210,7 @@ Every subscription returns an unsubscribe function and accepts `{ signal }` (an
 
 These rules are deterministic and frozen for the 1.x line once 1.0 ships:
 
-- **`update(dt)` order** — advance the timer by `dt × speed` (negative `dt` clamps to `0`); evaluate transitions; recompute the active frame; fire `onComplete` for a finished non-looping clip and then any `onEnd` auto-transition. An explicit input transition therefore wins over end-of-clip behaviour on the same frame.
+- **`update(dt)` order** — advance the timer by `dt × speed` (non-finite or non-positive `dt` clamps to `0`); evaluate transitions; recompute the active frame; fire `onComplete` for a finished non-looping clip and then any `onEnd` auto-transition. An explicit input transition therefore wins over end-of-clip behaviour on the same frame.
 - **Transition resolution** — among the transitions leaving the current state (plus **Any-State** `from: "*"`), candidates are ordered by `priority` (desc) then declared order (asc); the **first effective** one is taken. All `when` conditions must hold (logical AND).
 - **Self-transition rule** — a transition whose `to` equals the current state is *effective only if it consumes a Trigger*. A Number/Boolean self-loop is skipped, so it cannot reset the clip to frame 0 every frame. A trigger-bearing self-transition **restarts** the clip (e.g. re-attack) but does **not** fire `onStateChange` (the state name is unchanged).
 - **Triggers** — `fireTrigger(name)` marks a trigger pending; it stays pending across frames until a transition that checks it is taken, which **consumes** it. One fire → at most one transition.
@@ -195,12 +250,15 @@ Behavioural `vitest` suites cover inputs, transitions, trigger consumption, fram
 ```bash
 pnpm test        # run once
 pnpm coverage    # with thresholds
-pnpm example:platformer
+pnpm example:platformer  # renderer-free core demo
+pnpm example:explosion   # 6-frame play-once FX via the /pixi adapter
 ```
 
 ## Status
 
-**v0.1.1 — OIDC/SLSA publish.** The npm tarball now carries SLSA build provenance (OIDC trusted-publisher pipeline). No source or API changes from v0.1.0, which shipped all roadmap modules (1–4): the renderer-agnostic core (`.`), the PixiJS v8 adapter (`aispritejs/pixi`), the atlas parser (`aispritejs/atlas`), and the JSON Schema (`aispritejs/schema`). See [CHANGELOG.md](CHANGELOG.md) for the full history. Zero runtime dependencies; the root import graph contains no `pixi.js`; `pixi.js` is an optional, type-only peer used only by the `/pixi` subpath.
+**v0.1.3 — docs patch.** Adds a "When you DON'T need aispritejs" threshold and a complete, runnable 6-frame explosion (play-once FX) quickstart for the `/pixi` adapter; no source or API changes. v0.1.0 shipped all roadmap modules (1–4): the renderer-agnostic core (`.`), the PixiJS v8 adapter (`aispritejs/pixi`), the atlas parser (`aispritejs/atlas`), and the JSON Schema (`aispritejs/schema`); v0.1.1 added OIDC/SLSA publish provenance and v0.1.2 hardened validation — compile-time rejection of non-finite `speed` / `duration` / `defaultFrameDuration`, plus a runtime clamp of non-finite or non-positive `dt` (`dt <= 0`) to `0` in `update()`. See [CHANGELOG.md](CHANGELOG.md) for the full history. Zero runtime dependencies; the root import graph contains no `pixi.js`; `pixi.js` is an optional, type-only peer used only by the `/pixi` subpath.
+
+`aispritejs` is the newest package in the **ai\*js** family and follows its **own independent version line** — the `0.1.x` series reflects this package's own maturation, not alignment with any sibling's version number. Low usage in a given game (e.g. one built on static sprites) is expected, not a defect.
 
 ## Roadmap
 

package/README_ZHTW.md

@@ -19,6 +19,17 @@
 - **視覺 ≠ 邏輯。** 這嚴格來說是一個*視覺*動畫器，**不是**遊戲邏輯 FSM，也**不**相依 `aifsmjs`。用任何邏輯層（純程式、FSM、ECS）來驅動它 —— 它們以慣例組合，從不以相依耦合。
 - **輕巧又快。** O(1) 的輸入查找、對離開當前狀態的轉移做 O(N) 檢查、無每幀配置。
 
+## 何時你「不需要」aispritejs
+
+`aispritejs` 的價值在於影格選擇是**由執行期輸入驅動**、且橫跨**數個視覺狀態**時才會顯現。在這個門檻之下，直接用 PixiJS 就好 —— 用狀態機並無任何好處：
+
+- **單一 sprite／一張靜態圖片** → 純 PixiJS [`Sprite`](https://pixijs.download/release/docs/scene.Sprite.html)。沒有動畫、不需要圖集。
+- **單一循環片段、無任何分支**（轉動的金幣、閃爍的火把）→ PixiJS [`AnimatedSprite`](https://pixijs.download/release/docs/scene.AnimatedSprite.html)（`AnimatedSprite.fromFrames(...)`、`.play()`）。永遠以同一種方式播放的單一片段不需要輸入。
+- **沒有 texture atlas**（你並未把影格打包成 spritesheet）→ 直接載入圖片；`aispritejs` 從 PixiJS-v8 atlas（`animations` / `frames`）讀取它的影格。
+- **沒有多狀態切換** —— 若你的程式早已確切知道要播哪個片段、只需呼叫 `.play()` / `.gotoAndStop()`，你並不需要轉移圖。
+
+當你有**由輸入驅動、以 texture atlas 為後盾的多狀態視覺切換**時，才該動用 `aispritejs` —— 例如 `idle ⇄ walk → jump`，或由 trigger 觸發的一次性受擊 FX —— 此時畫面上顯示哪一格是 `speed` / `isGrounded` / `attack` 的函數，而非寫死的 `play()` 呼叫。
+
 ## 心智模型
 
 ```
@@ -70,6 +81,50 @@ view.fireTrigger("jump");
 
 它只在當前影格改變時換 texture，並尊重逐影格 `duration`（透過核心）與非置中／腳底樞軸（透過 `texture.defaultAnchor`；傳 `{ applyAnchor: false }` 可自行管理 anchor）。`view.sprite` 是綁定的 sprite；`dispose()` 拆除核心但不銷毀 sprite。
 
+### 完整範例 —— 一段 6 格爆炸（play-once FX）
+
+最常見的入門場景：一次性的受擊／撞擊 FX（水花、槍口閃光），來自一張 **6 格爆炸 sprite sheet**，透過 `/pixi` 轉接器驅動。一個 `Trigger` 觸發一段**非循環**片段，播放一次後經由 `onEnd` 自動回到靜止影格。完整可執行版本在 [`examples/02-explosion-pixi/index.ts`](examples/02-explosion-pixi/index.ts)（`pnpm example:explosion`）。
+
+```ts
+import { Assets, Sprite } from "pixi.js";
+import { createPixiSpriteAnimator } from "aispritejs/pixi";
+
+// 一張 6 格爆炸 sprite sheet（PixiJS-v8 atlas）：`animations` 區塊把片段
+// 命名 → 它的影格鍵；`frames` 帶有逐影格時長。
+const graph = {
+  animations: {
+    explosion: ["explosion_0", "explosion_1", "explosion_2", "explosion_3", "explosion_4", "explosion_5"],
+    idle: ["explosion_0"], // 一段 1 格的靜止片段，在每次爆發之間維持
+  },
+  frames: {
+    explosion_0: { duration: 40 }, explosion_1: { duration: 40 }, explosion_2: { duration: 40 },
+    explosion_3: { duration: 40 }, explosion_4: { duration: 40 }, explosion_5: { duration: 40 },
+  },
+  inputs: { detonate: { type: "trigger" } },
+  states: {
+    idle: { animation: "idle", loop: true },
+    boom: { animation: "explosion", loop: false, onEnd: "idle" }, // 播放一次 → 回到 idle
+  },
+  transitions: [
+    { from: "*", to: "boom", when: [{ input: "detonate", op: "Trigger" }], priority: 10 },
+  ],
+  initial: "idle",
+} as const;
+
+// 載入打包好的 sheet；它的 `.textures` 涵蓋 graph 用到的每一個影格鍵。
+const sheet = await Assets.load("explosion.json"); // 一個 PIXI.Spritesheet
+const sprite = new Sprite();
+const fx = createPixiSpriteAnimator(sprite, graph, sheet);
+
+// 在撞擊時觸發一次性 trigger：
+fx.fireTrigger("detonate");
+
+// 從你的 PixiJS render loop（例如 `app.ticker`）驅動這段爆發，依經過的
+// 毫秒數推進：`app.ticker.add((ticker) => fx.update(ticker.deltaMS))`。
+```
+
+`update(dt)` 把 `explosion_0…explosion_5` 播放一次（尊重每一格的 `duration`）；在播完片段的那一個 tick，它會觸發 `onComplete`，並因為 `boom` 宣告了 `onEnd`，在**同一個** tick 內自動轉移回 `idle` —— 所以不會停在最後一格，呼叫之後 `activeState` 立即讀到 `idle`。再次 `fireTrigger("detonate")` 即可重播。同一份 graph 在沒有渲染器時也能跑 —— 見 [`examples/02-explosion-pixi/index.ts`](examples/02-explosion-pixi/index.ts)，它以純 `Texture` / `Sprite` 實例、在無頭環境下操練真正的轉接器。
+
 ## 資料格式（atlas）
 
 `aispritejs` 讀取 **PixiJS v8 原生**的 spritesheet atlas（`meta` / `frames` / `animations`），並額外加上一個 `aispritejs` 的**輸入驅動**控制區塊：
@@ -147,7 +202,7 @@ anim.disposed;          // boolean
 
 這些規則是決定性的，並在 1.0 推出後對 1.x 凍結：
 
-- **`update(dt)` 順序** —— 以 `dt × speed` 推進計時器（負的 `dt` 夾到 `0`）；評估轉移；重算當前影格；為播完的非循環片段觸發 `onComplete`，接著執行任何 `onEnd` 自動轉移。因此同一幀內，明確的輸入轉移優先於片段結束行為。
+- **`update(dt)` 順序** —— 以 `dt × speed` 推進計時器（非有限或非正值的 `dt` 夾到 `0`）；評估轉移；重算當前影格；為播完的非循環片段觸發 `onComplete`，接著執行任何 `onEnd` 自動轉移。因此同一幀內，明確的輸入轉移優先於片段結束行為。
 - **轉移解析** —— 在離開當前狀態的轉移（加上 **Any-State** `from: "*"`）中，候選依 `priority`（遞減）再依宣告順序（遞增）排序；取**第一個有效**者。所有 `when` 條件須全部成立（邏輯 AND）。
 - **自我轉移規則** —— `to` 等於當前狀態的轉移，*只有在它消耗一個 Trigger 時才有效*。純 Number/Boolean 的自我迴圈會被跳過，因此不會每幀把片段重置回第 0 格。帶 trigger 的自我轉移會**重啟**片段（例如連續攻擊），但**不**觸發 `onStateChange`（狀態名稱沒變）。
 - **Triggers** —— `fireTrigger(name)` 把某 trigger 標記為 pending；它跨幀保持 pending，直到某個檢查它的轉移被採用而**消耗**它。一次 fire → 至多一次轉移。
@@ -198,7 +253,9 @@ pnpm example:platformer
 
 ## 狀態
 
-**v0.1.1 —— OIDC/SLSA 發佈。** npm tarball 現在帶有 SLSA build provenance（OIDC 受信任發行者流水線）。原始碼與 API 相較 v0.1.0 無變動，v0.1.0 一併 ship 所有 roadmap 模組 1–4：與渲染器無關的核心（`.`）、PixiJS v8 轉接器（`aispritejs/pixi`）、atlas parser（`aispritejs/atlas`）、JSON Schema（`aispritejs/schema`）。完整歷史請見 [CHANGELOG.md](CHANGELOG.md)。零執行期相依；根 import 圖不含 `pixi.js`；`pixi.js` 是選用、type-only 的 peer，僅 `/pixi` 子路徑用。
+**v0.1.3 —— 文件修補。** 新增「何時你『不需要』aispritejs」門檻，以及一個完整、可執行、針對 `/pixi` 轉接器的 6 格爆炸（play-once FX）快速範例；原始碼與 API 無變動。v0.1.0 一併 ship 所有 roadmap 模組 1–4：與渲染器無關的核心（`.`）、PixiJS v8 轉接器（`aispritejs/pixi`）、atlas parser（`aispritejs/atlas`）、JSON Schema（`aispritejs/schema`）；v0.1.1 加上 OIDC/SLSA 發佈 provenance，v0.1.2 強化驗證 —— 在編譯期拒絕非有限的 `speed` / `duration` / `defaultFrameDuration`，並在 `update()` 執行期把非有限或非正值（`dt <= 0`）的 `dt` 夾到 `0`。完整歷史請見 [CHANGELOG.md](CHANGELOG.md)。零執行期相依；根 import 圖不含 `pixi.js`；`pixi.js` 是選用、type-only 的 peer，僅 `/pixi` 子路徑用。
+
+`aispritejs` 是 **ai\*js** 家族中最新的套件，採用**自己獨立的版本線** —— `0.1.x` 系列反映的是這個套件自身的成熟度，而非與任何手足套件的版本號對齊。在某個遊戲裡使用率低（例如以靜態 sprite 為主的遊戲）是正常現象，並非缺陷。
 
 ## Roadmap
 

package/llms-full.txt

@@ -32,6 +32,17 @@ Part of the **ai\*js** family: zero cross-package dependencies, framework-agnost
 - **Visual ≠ logic.** This is strictly a *visual* animator. It is **not** a game-logic FSM and does **not** depend on `aifsmjs`. Drive it from any logic layer (plain code, an FSM, an ECS) — they compose by convention, never by dependency.
 - **Tiny + fast.** O(1) input lookups, O(N) checks over transitions leaving the current state, no per-frame allocation.
 
+## When you DON'T need aispritejs
+
+`aispritejs` earns its keep when frame selection is **driven by runtime inputs** across **several visual states**. Below that threshold, reach for PixiJS directly — there is nothing to gain from a state machine:
+
+- **A single sprite / one static image** → a plain PixiJS [`Sprite`](https://pixijs.download/release/docs/scene.Sprite.html). No animation, no graph.
+- **One looping clip with no branching** (a coin spin, a torch flicker) → a PixiJS [`AnimatedSprite`](https://pixijs.download/release/docs/scene.AnimatedSprite.html) (`AnimatedSprite.fromFrames(...)`, `.play()`). One clip that always plays the same way needs no inputs.
+- **No texture atlas** (you aren't packing frames into a spritesheet) → load images directly; `aispritejs` reads its frames from a PixiJS-v8 atlas (`animations` / `frames`).
+- **No multi-state switching** — if your code already knows exactly which clip to play and just calls `.play()` / `.gotoAndStop()`, you don't need a transition graph.
+
+Reach for `aispritejs` when you have **input-driven, multi-state visual switching backed by a texture atlas** — e.g. `idle ⇄ walk → jump`, or a one-shot hit FX fired by a trigger — where which frame is on screen is a function of `speed` / `isGrounded` / `attack`, not a hard-coded `play()` call.
+
 ## Mental model
 
 ```
@@ -85,6 +96,50 @@ It swaps the texture only when the active frame changes, and honours per-frame `
 
 Pass a plain `Sprite` — the adapter owns frame selection. (An `AnimatedSprite` is accepted since it extends `Sprite`, but its own playback is stopped on bind so it cannot fight the adapter for the texture.)
 
+### Complete example — a 6-frame explosion (play-once FX)
+
+The most common entry: a one-shot hit/impact FX (net-splash, muzzle flash) from a **6-frame explosion sprite sheet**, driven through the `/pixi` adapter. A `Trigger` fires a **non-looping** clip that plays once and auto-returns to a resting frame via `onEnd`. The full runnable version is [`examples/02-explosion-pixi/index.ts`](examples/02-explosion-pixi/index.ts) (`pnpm example:explosion`).
+
+```ts
+import { Assets, Sprite } from "pixi.js";
+import { createPixiSpriteAnimator } from "aispritejs/pixi";
+
+// A 6-frame explosion sprite sheet (PixiJS-v8 atlas): the `animations` block
+// names the clip → its frame keys; `frames` carries per-frame durations.
+const graph = {
+  animations: {
+    explosion: ["explosion_0", "explosion_1", "explosion_2", "explosion_3", "explosion_4", "explosion_5"],
+    idle: ["explosion_0"], // a 1-frame resting clip to hold between bursts
+  },
+  frames: {
+    explosion_0: { duration: 40 }, explosion_1: { duration: 40 }, explosion_2: { duration: 40 },
+    explosion_3: { duration: 40 }, explosion_4: { duration: 40 }, explosion_5: { duration: 40 },
+  },
+  inputs: { detonate: { type: "trigger" } },
+  states: {
+    idle: { animation: "idle", loop: true },
+    boom: { animation: "explosion", loop: false, onEnd: "idle" }, // play once → back to idle
+  },
+  transitions: [
+    { from: "*", to: "boom", when: [{ input: "detonate", op: "Trigger" }], priority: 10 },
+  ],
+  initial: "idle",
+} as const;
+
+// Load the packed sheet; its `.textures` cover every frame key the graph uses.
+const sheet = await Assets.load("explosion.json"); // a PIXI.Spritesheet
+const sprite = new Sprite();
+const fx = createPixiSpriteAnimator(sprite, graph, sheet);
+
+// Fire the one-shot trigger on impact:
+fx.fireTrigger("detonate");
+
+// Drive the burst from your PixiJS render loop (e.g. `app.ticker`), advancing by
+// elapsed ms: `app.ticker.add((ticker) => fx.update(ticker.deltaMS))`.
+```
+
+`update(dt)` plays `explosion_0…explosion_5` once (honouring each frame's `duration`); on the tick that completes the clip it fires `onComplete` and, because `boom` declares `onEnd`, auto-transitions to `idle` in that **same** tick — so the last frame isn't held, and `activeState` reads `idle` right after. Re-`fireTrigger("detonate")` to replay. The same graph runs with no renderer — see [`examples/02-explosion-pixi/index.ts`](examples/02-explosion-pixi/index.ts), which exercises the real adapter headlessly with plain `Texture` / `Sprite` instances.
+
 ## Data format (atlas)
 
 `aispritejs` reads a **PixiJS v8-native** spritesheet atlas (`meta` / `frames` / `animations`) — the same shape the family's sprite pipeline emits — augmented with an `aispritejs` **input-driven** control block:
@@ -168,7 +223,7 @@ Every subscription returns an unsubscribe function and accepts `{ signal }` (an
 
 These rules are deterministic and frozen for the 1.x line once 1.0 ships:
 
-- **`update(dt)` order** — advance the timer by `dt × speed` (negative `dt` clamps to `0`); evaluate transitions; recompute the active frame; fire `onComplete` for a finished non-looping clip and then any `onEnd` auto-transition. An explicit input transition therefore wins over end-of-clip behaviour on the same frame.
+- **`update(dt)` order** — advance the timer by `dt × speed` (non-finite or non-positive `dt` clamps to `0`); evaluate transitions; recompute the active frame; fire `onComplete` for a finished non-looping clip and then any `onEnd` auto-transition. An explicit input transition therefore wins over end-of-clip behaviour on the same frame.
 - **Transition resolution** — among the transitions leaving the current state (plus **Any-State** `from: "*"`), candidates are ordered by `priority` (desc) then declared order (asc); the **first effective** one is taken. All `when` conditions must hold (logical AND).
 - **Self-transition rule** — a transition whose `to` equals the current state is *effective only if it consumes a Trigger*. A Number/Boolean self-loop is skipped, so it cannot reset the clip to frame 0 every frame. A trigger-bearing self-transition **restarts** the clip (e.g. re-attack) but does **not** fire `onStateChange` (the state name is unchanged).
 - **Triggers** — `fireTrigger(name)` marks a trigger pending; it stays pending across frames until a transition that checks it is taken, which **consumes** it. One fire → at most one transition.
@@ -208,12 +263,15 @@ Behavioural `vitest` suites cover inputs, transitions, trigger consumption, fram
 ```bash
 pnpm test        # run once
 pnpm coverage    # with thresholds
-pnpm example:platformer
+pnpm example:platformer  # renderer-free core demo
+pnpm example:explosion   # 6-frame play-once FX via the /pixi adapter
 ```
 
 ## Status
 
-**v0.1.1 — OIDC/SLSA publish.** The npm tarball now carries SLSA build provenance (OIDC trusted-publisher pipeline). No source or API changes from v0.1.0, which shipped all roadmap modules (1–4): the renderer-agnostic core (`.`), the PixiJS v8 adapter (`aispritejs/pixi`), the atlas parser (`aispritejs/atlas`), and the JSON Schema (`aispritejs/schema`). See [CHANGELOG.md](CHANGELOG.md) for the full history. Zero runtime dependencies; the root import graph contains no `pixi.js`; `pixi.js` is an optional, type-only peer used only by the `/pixi` subpath.
+**v0.1.3 — docs patch.** Adds a "When you DON'T need aispritejs" threshold and a complete, runnable 6-frame explosion (play-once FX) quickstart for the `/pixi` adapter; no source or API changes. v0.1.0 shipped all roadmap modules (1–4): the renderer-agnostic core (`.`), the PixiJS v8 adapter (`aispritejs/pixi`), the atlas parser (`aispritejs/atlas`), and the JSON Schema (`aispritejs/schema`); v0.1.1 added OIDC/SLSA publish provenance and v0.1.2 hardened validation — compile-time rejection of non-finite `speed` / `duration` / `defaultFrameDuration`, plus a runtime clamp of non-finite or non-positive `dt` (`dt <= 0`) to `0` in `update()`. See [CHANGELOG.md](CHANGELOG.md) for the full history. Zero runtime dependencies; the root import graph contains no `pixi.js`; `pixi.js` is an optional, type-only peer used only by the `/pixi` subpath.
+
+`aispritejs` is the newest package in the **ai\*js** family and follows its **own independent version line** — the `0.1.x` series reflects this package's own maturation, not alignment with any sibling's version number. Low usage in a given game (e.g. one built on static sprites) is expected, not a defect.
 
 ## Roadmap
 
@@ -236,6 +294,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-06-05
+
+### Added
+
+- Docs: a "When you DON'T need aispritejs" threshold section and a complete, runnable 6-frame
+  explosion (play-once FX) `/pixi` quickstart (`examples/02-explosion-pixi`); no source/API changes.
+
 ## [0.1.2] - 2026-06-05
 
 ### Changed
@@ -362,7 +427,9 @@ parser, and JSON Schema (roadmap modules 1–4).
   / lines (above the family floor of 95 / 90 / 100 / 100). Core gzip ≈ 3.5 KB.
 - OIDC + SLSA provenance publish on tag-push.
 
-[Unreleased]: https://github.com/yshengliao/aispritejs/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/yshengliao/aispritejs/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/yshengliao/aispritejs/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/yshengliao/aispritejs/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/yshengliao/aispritejs/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/yshengliao/aispritejs/releases/tag/v0.1.0
 
@@ -472,4 +539,29 @@ classic `idle` / `walk` / `jump` graph and exercises every core idea:
 The same `graph` object would drive a PixiJS sprite unchanged via the
 `aispritejs/pixi` adapter — the core never knows a renderer exists.
 
+## 02 — explosion (PixiJS v8 adapter)
+
+```bash
+pnpm example:explosion
+```
+
+[`02-explosion-pixi/index.ts`](examples/02-explosion-pixi/index.ts) is the most-common
+entry: a **6-frame explosion sprite sheet** (net-splash / hit FX) bound through
+the real `aispritejs/pixi` adapter:
+
+- the atlas `animations` block lists the six frame keys, with per-frame `frames`
+  durations (a snappy ~40 ms/frame burst);
+- a **Trigger** (`detonate`) fires an Any-State transition into a **non-looping**
+  `boom` state that **plays once** and auto-returns to a resting `idle` frame via
+  `onEnd`;
+- `createPixiSpriteAnimator(sprite, graph, textures)` binds a real `PIXI.Sprite`;
+  each `update(dt)` swaps `sprite.texture` to the active frame and applies that
+  frame's atlas `defaultAnchor`;
+- it runs headlessly in Node — the adapter only touches `sprite.texture` /
+  `sprite.anchor` / `texture.defaultAnchor`, so plain `PIXI.Texture` / `Sprite`
+  instances exercise the real API (no GPU or canvas needed).
+
+This is the play-once FX shape to reach for when you have input-driven,
+multi-state visual switching backed by a texture atlas.
+
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aispritejs",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Input-driven, renderer-agnostic 2D sprite animation runtime — a tiny, Rive-like visual state machine driven by Number / Boolean / Trigger inputs. JSON transition graph, deterministic update(dt), zero runtime dependencies. Browser / Node / Bun / Deno / WebView / Worker friendly.",
   "keywords": [
     "sprite",
@@ -73,6 +73,7 @@
     "verify:llms": "node scripts/build-llms-full.mjs --check",
     "coverage": "vitest run --coverage",
     "example:platformer": "tsx examples/01-platformer-inputs/index.ts",
+    "example:explosion": "tsx examples/02-explosion-pixi/index.ts",
     "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm coverage && pnpm build && pnpm verify:exports && pnpm verify:llms && pnpm check:size"
   },
   "peerDependencies": {