aispritejs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yshengliao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# aispritejs
+
+[![npm version](https://img.shields.io/npm/v/aispritejs.svg)](https://www.npmjs.com/package/aispritejs)
+[![CI](https://github.com/yshengliao/aispritejs/actions/workflows/ci.yml/badge.svg)](https://github.com/yshengliao/aispritejs/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
+[![AI Generated](https://img.shields.io/badge/AI_Generated-yes-blueviolet.svg)](https://www.anthropic.com/claude-code)
+[![繁體中文](https://img.shields.io/badge/lang-繁體中文-red.svg)](README_ZHTW.md)
+
+> Input-driven, renderer-agnostic 2D sprite animation runtime — a tiny, Rive-like *visual* state machine driven by `Number` / `Boolean` / `Trigger` inputs.
+
+`aispritejs` decides **which animation frame is on screen** from a small set of runtime **inputs** (e.g. `speed`, `isGrounded`, `jump`), using a JSON-defined transition graph. Your code sets inputs; `aispritejs` picks the visual state and ticks the active frame. The core is pure TypeScript with **zero dependencies** and **no renderer imports** — bind it to PixiJS v8 (or anything) through a thin adapter.
+
+Part of the **ai\*js** family: zero cross-package dependencies, framework-agnostic core, AI-readable docs.
+
+## Why aispritejs
+
+- **Input-driven, not name-driven.** You set parameters (`speed=4`, `isGrounded=false`, `fireTrigger("jump")`), not animation names. Visual transitions live in data, decoupled from game code.
+- **Renderer-agnostic core.** The state machine computes the active frame from delta-time + inputs; it never imports PixiJS or touches the DOM. Adapters map the result to textures.
+- **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.
+
+## Mental model
+
+```
+inputs ─▶ [transition graph] ─▶ active state ─▶ (Δt) ─▶ active frame ─▶ adapter ─▶ texture
+```
+
+- **Inputs** — `Number` (continuous, e.g. `speed`), `Boolean` (toggle, e.g. `isGrounded`), `Trigger` (one-shot; auto-resets after a transition consumes it, e.g. `jump` / `attack`).
+- **States** — an animation key (into the atlas `animations`) + loop / on-end behaviour + optional speed multiplier.
+- **Transitions** — from a state (or **Any State**) to another when conditions over inputs hold (`Equals` / `NotEquals` / `GreaterThan` / `LessThan`). The highest-priority satisfied transition wins.
+- **`update(dt)`** — advances the playback timer; evaluates transitions (switching state, firing `onStateChange`, consuming triggers); computes the current frame from the animation's per-frame durations + loop; fires `onComplete` when a non-looping clip ends.
+
+## Quick start — core (zero-dep)
+
+```ts
+import { createSpriteAnimator } from "aispritejs";
+
+const anim = createSpriteAnimator(graph); // graph = { inputs, states, transitions, animations }
+
+anim.setInput("speed", 4);
+anim.setInput("isGrounded", true);
+anim.fireTrigger("jump");
+
+anim.onStateChange((to, from) => {/* ... */});
+anim.onComplete((state) => {/* ... */});
+
+// in your render loop:
+anim.update(deltaMs);
+const frameKey = anim.activeFrameKey; // hand to your renderer
+```
+
+## Quick start — PixiJS v8 adapter
+
+The `aispritejs/pixi` subpath binds the core to a `PIXI.Sprite`. `pixi.js` is an **optional** `peerDependency`, imported **type-only** — the built adapter contains no runtime `pixi.js` require, and the core never imports it.
+
+```ts
+import { createPixiSpriteAnimator } from "aispritejs/pixi"; // pixi.js is an OPTIONAL peer
+
+// `textures` is a PIXI.Spritesheet (or a frame-key → Texture map) covering
+// every frame the graph references — missing keys throw MissingTextureError.
+const view = createPixiSpriteAnimator(sprite, graph, spritesheet);
+
+// each frame:
+view.update(deltaMs); // swaps the bound sprite's texture to the active frame,
+                      // applying that frame's atlas anchor (texture.defaultAnchor)
+
+view.setInput("speed", 4);
+view.fireTrigger("jump");
+```
+
+It swaps the texture only when the active frame changes, and honours per-frame `duration` (via the core) and non-centre / foot pivots (via `texture.defaultAnchor`; pass `{ applyAnchor: false }` to manage the anchor yourself). `view.sprite` is the bound sprite; `dispose()` tears down the core without destroying the sprite.
+
+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.)
+
+## 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:
+
+```jsonc
+{
+  "meta":   { "image": "sheet.png", "size": { "w": 1024, "h": 1024 }, "scale": "1" },
+  "frames": { /* PixiJS native: frame{x,y,w,h}, anchor, duration, trimmed, ... */ },
+  "animations": { "idle": ["idle_0", "idle_1"], "walk": ["walk_0", "..."], "jump": ["jump_0", "..."] },
+
+  "inputs": {
+    "speed":      { "type": "number",  "default": 0 },
+    "isGrounded": { "type": "boolean", "default": true },
+    "jump":       { "type": "trigger" }
+  },
+  "states": {
+    "idle": { "animation": "idle", "loop": true },
+    "walk": { "animation": "walk", "loop": true },
+    "jump": { "animation": "jump", "loop": false }
+  },
+  "transitions": [
+    { "from": "*",    "to": "jump", "when": [{ "input": "jump",  "op": "Trigger" }], "priority": 10 },
+    { "from": "idle", "to": "walk", "when": [{ "input": "speed", "op": "GreaterThan", "value": 0 }] },
+    { "from": "walk", "to": "idle", "when": [{ "input": "speed", "op": "Equals",      "value": 0 }] }
+  ]
+}
+```
+
+This **input-driven** model is deliberately distinct from an event-driven FSM. `aispritejs` ingests only the universal `frames` / `animations`; the `inputs` / `states` / `transitions` are its own. If an atlas carries a foreign event-driven `states` block from another tool, `aispritejs` ignores it.
+
+## Loading an atlas — `aispritejs/atlas`
+
+The `aispritejs/atlas` subpath turns a parsed PixiJS-v8 atlas into a graph (or a ready animator). It is pure and zero-dependency.
+
+```ts
+import { parseAtlas, loadAtlas } from "aispritejs/atlas";
+
+// Augmented atlas (the shape above, with inputs/states/transitions inline):
+const anim = loadAtlas(atlasJson);
+
+// Real atlas whose own `states` block is foreign (event-driven) or absent —
+// supply the input-driven control separately; the foreign block is ignored:
+const graph = parseAtlas(atlasJson, { inputs, states, transitions, initial });
+```
+
+- `parseAtlas(atlas, control?)` → `SpriteGraph`; `loadAtlas(atlas, control?)` → `SpriteAnimator` (parse + create in one fail-fast step).
+- A foreign event-driven `states` block (the `{ initial, definitions }` FSM shape) is **detected and ignored** — pass an `aispritejs` control block instead. Structural problems throw `InvalidAtlasError`; semantic ones surface as `InvalidGraphError` from the core.
+- The canonical structure is published as a JSON Schema at [`schemas/aispritejs-graph.schema.json`](schemas/aispritejs-graph.schema.json) (also exported as `aispritejs/schema`) for editor and CI validation; the parser mirrors it in code, so there is no runtime schema-validator dependency.
+
+## Decoupling (P0)
+
+- **Zero cross-package imports** — `aispritejs` does not import `aifsmjs`, `aieventjs`, or any sibling. It has its own minimal typed emitter.
+- **Renderer-agnostic core** — the root entry never imports `pixi.js`. Only `aispritejs/pixi` does, and `pixi.js` is an **optional `peerDependency`**.
+- **Visual animator only** — pair it with a game-logic layer by setting inputs; it makes no assumption about how your logic is structured.
+
+## Core API
+
+The public surface is a single factory plus types and named errors. There is **no exported class constructor** — `createSpriteAnimator` returns a `SpriteAnimator`.
+
+```ts
+const anim = createSpriteAnimator(graph); // throws InvalidGraphError on a bad graph
+
+anim.setInput(name, value);   // Number | Boolean; throws Unknown/InputTypeError
+anim.fireTrigger(name);       // marks a Trigger pending
+anim.update(deltaMs);         // advance; evaluate transitions; tick the frame
+anim.reset();                 // back to initial + default inputs (keeps buffers)
+anim.dispose();               // idempotent; mutators throw afterwards
+
+const off = anim.onStateChange((to, from) => {}, { signal?, once? }); // → unsubscribe
+const off2 = anim.onComplete((state) => {}, { signal?, once? });
+
+anim.activeState;       // current state name
+anim.activeFrameKey;    // frame key into the atlas `frames` — hand to a renderer
+anim.activeFrameIndex;  // index within the active animation
+anim.disposed;          // boolean
+```
+
+Every subscription returns an unsubscribe function and accepts `{ signal }` (an `AbortSignal` that removes the listener) and `{ once }`.
+
+## Semantics (the precise rules)
+
+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.
+- **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.
+- **Frame timing** — the active frame is the first whose cumulative duration exceeds the elapsed time. Looping clips wrap at the total duration; non-looping clips hold the last frame and fire `onComplete` exactly once. Per-frame `duration` comes from the atlas `frames`; frames without one use `defaultFrameDuration` (default `100` ms). `speed` is a time-scale multiplier (`2` = twice as fast).
+- **Determinism** — identical input + `dt` sequences always yield identical frame sequences. The no-transition path allocates nothing.
+
+## Errors
+
+Named errors, never bare throws:
+
+- `InvalidGraphError` — thrown by `createSpriteAnimator` when the graph fails validation (missing animation, unknown transition target, operator/kind mismatch, non-positive duration/speed, `onEnd` with `loop:true`, …). Fail-fast: an invalid graph never yields a half-built animator.
+- `UnknownInputError` — `setInput` / `fireTrigger` on an input not declared in `inputs` (carries `.input`).
+- `InputTypeError` — wrong value type, `setInput` on a Trigger, or `fireTrigger` on a non-Trigger (carries `.input`).
+- `SpriteAnimatorDisposedError` — any mutator (`setInput` / `fireTrigger` / `update` / `reset`) after `dispose()`.
+
+## Comparison
+
+| | aispritejs | Rive | aifsmjs | raw `AnimatedSprite` |
+|---|---|---|---|---|
+| Control model | input-driven (Number/Boolean/Trigger) | input-driven | event-driven (logic) | manual |
+| Scope | visual animation | visual animation | game logic | playback only |
+| Runtime | tiny TS, no wasm | wasm runtime | tiny TS | — |
+| Renderer | agnostic + adapters | own | n/a | PixiJS |
+
+`aispritejs` and `aifsmjs` are complementary — logic FSM sets inputs, visual animator picks frames — and never coupled.
+
+## AI-agent reading guide
+
+- **Whole context in one fetch** — [`llms-full.txt`](llms-full.txt) concatenates this README, the changelog, the contributing guide, and the examples index.
+- **Source layout** — the core lives in [`src/sprite/`](src/sprite/): `types.ts` (every public type in one file), `machine.ts` (the `createSpriteAnimator` engine), `compile.ts` (graph validation + normalisation), `inputs.ts` (the input store), `emitter.ts` (the own typed signal), `errors.ts`. The root [`src/index.ts`](src/index.ts) re-exports the public surface and imports **no** renderer.
+- **Stability tiers** — see [STABILITY.md](STABILITY.md).
+
+## Testing
+
+Behavioural `vitest` suites cover inputs, transitions, trigger consumption, frame timing, `onComplete` / `onEnd`, subscriptions (`signal` / `once`), `dispose` / `reset`, and graph validation. `fast-check` property tests assert **transition determinism** (identical input + `dt` sequences ⇒ identical frame traces) and **trigger consumption** (one fire ⇒ one entry). Coverage runs at the family floor (≥95 % statements / ≥90 % branches / 100 % functions-and-lines).
+
+```bash
+pnpm test        # run once
+pnpm coverage    # with thresholds
+pnpm example:platformer
+```
+
+## Status
+
+**v0.1.0 — full first release.** All roadmap modules (1–4) ship together: the renderer-agnostic core (`.`), the PixiJS v8 adapter (`aispritejs/pixi`), the atlas parser (`aispritejs/atlas`), and the JSON Schema (`aispritejs/schema`). 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. Versioning and release tags are cut by the maintainer.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md).
+
+## License
+
+MIT © yshengliao — see [LICENSE](LICENSE).

package/README_ZHTW.md

@@ -0,0 +1,209 @@
+# aispritejs
+
+[![npm version](https://img.shields.io/npm/v/aispritejs.svg)](https://www.npmjs.com/package/aispritejs)
+[![CI](https://github.com/yshengliao/aispritejs/actions/workflows/ci.yml/badge.svg)](https://github.com/yshengliao/aispritejs/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
+[![AI Generated](https://img.shields.io/badge/AI_Generated-yes-blueviolet.svg)](https://www.anthropic.com/claude-code)
+[![English](https://img.shields.io/badge/lang-English-blue.svg)](README.md)
+
+> 以輸入驅動、與渲染器無關的 2D sprite 動畫 runtime —— 一個輕巧、類 Rive 的*視覺*狀態機，由 `Number` / `Boolean` / `Trigger` 輸入驅動。
+
+`aispritejs` 依據一小組執行期**輸入**（例如 `speed`、`isGrounded`、`jump`），透過 JSON 定義的轉移圖，決定**畫面上要顯示哪一格動畫影格**。你的程式設定輸入，`aispritejs` 挑選視覺狀態並推進當前影格。核心是純 TypeScript，**零相依**且**不 import 任何渲染器** —— 透過薄薄一層轉接器即可接上 PixiJS v8（或任何東西）。
+
+屬於 **ai\*js** 家族：零跨套件相依、核心與框架無關、AI 可讀的文件。
+
+## 為什麼用 aispritejs
+
+- **輸入驅動，而非名稱驅動。** 你設定參數（`speed=4`、`isGrounded=false`、`fireTrigger("jump")`），而不是動畫名稱。視覺轉移存在於資料中，與遊戲程式解耦。
+- **核心與渲染器無關。** 狀態機從 delta-time 加上輸入算出當前影格；它從不 import PixiJS 也不碰 DOM。轉接器負責把結果對映成 texture。
+- **視覺 ≠ 邏輯。** 這嚴格來說是一個*視覺*動畫器，**不是**遊戲邏輯 FSM，也**不**相依 `aifsmjs`。用任何邏輯層（純程式、FSM、ECS）來驅動它 —— 它們以慣例組合，從不以相依耦合。
+- **輕巧又快。** O(1) 的輸入查找、對離開當前狀態的轉移做 O(N) 檢查、無每幀配置。
+
+## 心智模型
+
+```
+inputs ─▶ [轉移圖] ─▶ 當前狀態 ─▶ (Δt) ─▶ 當前影格 ─▶ 轉接器 ─▶ texture
+```
+
+- **Inputs（輸入）** —— `Number`（連續，如 `speed`）、`Boolean`（開關，如 `isGrounded`）、`Trigger`（一次性；被某個轉移消耗後自動重置，如 `jump` / `attack`）。
+- **States（狀態）** —— 一個動畫鍵（指向 atlas 的 `animations`）加上 loop / on-end 行為與選用的速度倍率。
+- **Transitions（轉移）** —— 當輸入條件成立時（`Equals` / `NotEquals` / `GreaterThan` / `LessThan`），從某狀態（或 **Any State**）轉到另一狀態。優先度最高且成立者勝出。
+- **`update(dt)`** —— 推進播放計時器；評估轉移（切換狀態、觸發 `onStateChange`、消耗 trigger）；由動畫的逐影格時長加 loop 算出當前影格；非循環片段播完時觸發 `onComplete`。
+
+## 快速開始 —— 核心（零相依）
+
+```ts
+import { createSpriteAnimator } from "aispritejs";
+
+const anim = createSpriteAnimator(graph); // graph = { inputs, states, transitions, animations }
+
+anim.setInput("speed", 4);
+anim.setInput("isGrounded", true);
+anim.fireTrigger("jump");
+
+anim.onStateChange((to, from) => {/* ... */});
+anim.onComplete((state) => {/* ... */});
+
+// 在你的 render loop 裡：
+anim.update(deltaMs);
+const frameKey = anim.activeFrameKey; // 交給你的渲染器
+```
+
+## 快速開始 —— PixiJS v8 轉接器
+
+`aispritejs/pixi` 子路徑把核心綁到一個 `PIXI.Sprite`。`pixi.js` 是**選用的** `peerDependency`，且僅以 **type-only** 方式 import —— 編譯後的轉接器不含任何 `pixi.js` runtime require，核心也永不碰它。
+
+```ts
+import { createPixiSpriteAnimator } from "aispritejs/pixi"; // pixi.js 是選用 peer
+
+// `textures` 是 PIXI.Spritesheet（或 frame-key → Texture 的 map），需涵蓋 graph
+// 參照的每一格 —— 缺鍵會丟出 MissingTextureError。
+const view = createPixiSpriteAnimator(sprite, graph, spritesheet);
+
+// 每幀：
+view.update(deltaMs); // 把綁定 sprite 的 texture 換成當前影格，
+                      // 並套用該格的 atlas anchor（texture.defaultAnchor）
+
+view.setInput("speed", 4);
+view.fireTrigger("jump");
+```
+
+它只在當前影格改變時換 texture，並尊重逐影格 `duration`（透過核心）與非置中／腳底樞軸（透過 `texture.defaultAnchor`；傳 `{ applyAnchor: false }` 可自行管理 anchor）。`view.sprite` 是綁定的 sprite；`dispose()` 拆除核心但不銷毀 sprite。
+
+## 資料格式（atlas）
+
+`aispritejs` 讀取 **PixiJS v8 原生**的 spritesheet atlas（`meta` / `frames` / `animations`），並額外加上一個 `aispritejs` 的**輸入驅動**控制區塊：
+
+```jsonc
+{
+  "meta":   { "image": "sheet.png", "size": { "w": 1024, "h": 1024 }, "scale": "1" },
+  "frames": { /* PixiJS 原生：frame{x,y,w,h}、anchor、duration、trimmed... */ },
+  "animations": { "idle": ["idle_0", "idle_1"], "walk": ["walk_0", "..."], "jump": ["jump_0", "..."] },
+
+  "inputs": {
+    "speed":      { "type": "number",  "default": 0 },
+    "isGrounded": { "type": "boolean", "default": true },
+    "jump":       { "type": "trigger" }
+  },
+  "states": {
+    "idle": { "animation": "idle", "loop": true },
+    "walk": { "animation": "walk", "loop": true },
+    "jump": { "animation": "jump", "loop": false }
+  },
+  "transitions": [
+    { "from": "*",    "to": "jump", "when": [{ "input": "jump",  "op": "Trigger" }], "priority": 10 },
+    { "from": "idle", "to": "walk", "when": [{ "input": "speed", "op": "GreaterThan", "value": 0 }] },
+    { "from": "walk", "to": "idle", "when": [{ "input": "speed", "op": "Equals",      "value": 0 }] }
+  ]
+}
+```
+
+這個**輸入驅動**模型刻意與事件驅動 FSM 區隔。`aispritejs` 只吃通用的 `frames` / `animations`；`inputs` / `states` / `transitions` 屬於它自己。若某個 atlas 帶有來自其他工具的事件驅動 `states` 區塊，`aispritejs` 會忽略它。
+
+## 載入 atlas —— `aispritejs/atlas`
+
+`aispritejs/atlas` 子路徑把已解析的 PixiJS v8 atlas 轉成 graph（或現成的 animator）。它是純函式且零相依。
+
+```ts
+import { parseAtlas, loadAtlas } from "aispritejs/atlas";
+
+// 增強型 atlas（上述形狀，inputs/states/transitions 內嵌）：
+const anim = loadAtlas(atlasJson);
+
+// 真實 atlas 的 `states` 是 foreign（事件驅動）或不存在 —— 另外傳入輸入驅動
+// 控制區塊；foreign 區塊會被忽略：
+const graph = parseAtlas(atlasJson, { inputs, states, transitions, initial });
+```
+
+- `parseAtlas(atlas, control?)` → `SpriteGraph`；`loadAtlas(atlas, control?)` → `SpriteAnimator`（一步 parse + create，fail-fast）。
+- foreign 事件驅動 `states`（`{ initial, definitions }` 的 FSM 形狀）會被**偵測並忽略** —— 改傳 `aispritejs` 控制區塊。結構問題丟出 `InvalidAtlasError`；語意問題由核心丟出 `InvalidGraphError`。
+- 標準結構以 JSON Schema 發佈於 [`schemas/aispritejs-graph.schema.json`](schemas/aispritejs-graph.schema.json)（亦匯出為 `aispritejs/schema`），供編輯器與 CI 驗證；parser 以程式碼鏡像它，因此無 runtime schema-validator 相依。
+
+## 核心 API
+
+公開介面是單一工廠函式，加上型別與具名錯誤。**不匯出任何 class 建構子** —— `createSpriteAnimator` 回傳一個 `SpriteAnimator`。
+
+```ts
+const anim = createSpriteAnimator(graph); // graph 不合法時丟出 InvalidGraphError
+
+anim.setInput(name, value);   // Number | Boolean；丟出 Unknown/InputTypeError
+anim.fireTrigger(name);       // 將某個 Trigger 標記為 pending
+anim.update(deltaMs);         // 推進；評估轉移；推進影格
+anim.reset();                 // 回到初始狀態與預設輸入（保留 buffer）
+anim.dispose();               // 冪等；之後呼叫 mutator 會丟錯
+
+const off = anim.onStateChange((to, from) => {}, { signal?, once? }); // → 取消訂閱
+const off2 = anim.onComplete((state) => {}, { signal?, once? });
+
+anim.activeState;       // 當前狀態名稱
+anim.activeFrameKey;    // 指向 atlas `frames` 的影格鍵 —— 交給渲染器
+anim.activeFrameIndex;  // 在當前動畫中的索引
+anim.disposed;          // boolean
+```
+
+每個訂閱都回傳一個取消訂閱函式，並接受 `{ signal }`（用 `AbortSignal` 移除監聽）與 `{ once }`。
+
+## 語意（精確規則）
+
+這些規則是決定性的，並在 1.0 推出後對 1.x 凍結：
+
+- **`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 → 至多一次轉移。
+- **影格時序** —— 當前影格是累積時長首次超過已經過時間的那一格。循環片段在總時長處回繞；非循環片段停在最後一格並只觸發一次 `onComplete`。逐影格 `duration` 取自 atlas `frames`；沒有的影格採用 `defaultFrameDuration`（預設 `100` ms）。`speed` 是時間倍率（`2` = 兩倍速）。
+- **決定性** —— 相同的輸入加 `dt` 序列必產生相同的影格序列。無轉移的路徑不做任何配置。
+
+## 錯誤
+
+具名錯誤，從不裸 throw：
+
+- `InvalidGraphError` —— `createSpriteAnimator` 在 graph 驗證失敗時丟出（缺少動畫、未知的轉移目標、運算子/型別不符、非正的時長/速度、`onEnd` 配 `loop:true`…）。Fail-fast：不合法的 graph 絕不產出半成品動畫器。
+- `UnknownInputError` —— 對 `inputs` 未宣告的輸入呼叫 `setInput` / `fireTrigger`（帶有 `.input`）。
+- `InputTypeError` —— 值型別錯誤、對 Trigger 呼叫 `setInput`、或對非 Trigger 呼叫 `fireTrigger`（帶有 `.input`）。
+- `SpriteAnimatorDisposedError` —— `dispose()` 之後呼叫任何 mutator（`setInput` / `fireTrigger` / `update` / `reset`）。
+
+## 解耦（P0）
+
+- **零跨套件 import** —— `aispritejs` 不 import `aifsmjs`、`aieventjs` 或任何手足套件。它有自己最小的具名 emitter。
+- **核心與渲染器無關** —— 根進入點永不 import `pixi.js`。只有 `aispritejs/pixi` 會，而 `pixi.js` 是**選用的** `peerDependency`。
+- **僅是視覺動畫器** —— 用設定輸入的方式搭配遊戲邏輯層；它不假設你的邏輯如何組織。
+
+## 比較
+
+| | aispritejs | Rive | aifsmjs | 原生 `AnimatedSprite` |
+|---|---|---|---|---|
+| 控制模型 | 輸入驅動（Number/Boolean/Trigger） | 輸入驅動 | 事件驅動（邏輯） | 手動 |
+| 範圍 | 視覺動畫 | 視覺動畫 | 遊戲邏輯 | 僅播放 |
+| Runtime | 輕巧 TS，無 wasm | wasm runtime | 輕巧 TS | — |
+| 渲染器 | 無關 + 轉接器 | 自帶 | n/a | PixiJS |
+
+`aispritejs` 與 `aifsmjs` 互補 —— 邏輯 FSM 設定輸入、視覺動畫器挑影格 —— 且永不耦合。
+
+## 給 AI agent 的閱讀指南
+
+- **一次抓完整 context** —— [`llms-full.txt`](llms-full.txt) 串接了本 README、changelog、contributing 指南與範例索引。
+- **原始碼版面** —— 核心位於 [`src/sprite/`](src/sprite/)：`types.ts`（所有公開型別集中一檔）、`machine.ts`（`createSpriteAnimator` 引擎）、`compile.ts`（graph 驗證與正規化）、`inputs.ts`（輸入儲存）、`emitter.ts`（自有具名 signal）、`errors.ts`。根 [`src/index.ts`](src/index.ts) 再匯出公開介面，且**不** import 任何渲染器。
+- **穩定度分級** —— 見 [STABILITY.md](STABILITY.md)。
+
+## 測試
+
+`vitest` 行為測試涵蓋輸入、轉移、trigger 消耗、影格時序、`onComplete` / `onEnd`、訂閱（`signal` / `once`）、`dispose` / `reset` 與 graph 驗證。`fast-check` 屬性測試驗證**轉移決定性**（相同輸入加 `dt` 序列 ⇒ 相同影格軌跡）與 **trigger 消耗**（一次 fire ⇒ 一次進入）。覆蓋率以家族下限執行（≥95% statements / ≥90% branches / 100% functions 與 lines）。
+
+```bash
+pnpm test        # 跑一次
+pnpm coverage    # 帶門檻
+pnpm example:platformer
+```
+
+## 狀態
+
+**v0.1.0 —— 完整首發。** roadmap 模組 1–4 一併 ship：與渲染器無關的核心（`.`）、PixiJS v8 轉接器（`aispritejs/pixi`）、atlas parser（`aispritejs/atlas`）、JSON Schema（`aispritejs/schema`）。零執行期相依；根 import 圖不含 `pixi.js`；`pixi.js` 是選用、type-only 的 peer,僅 `/pixi` 子路徑用。版本號與發佈 tag 由維護者切。
+
+## Roadmap
+
+見 [ROADMAP.md](ROADMAP.md)。
+
+## License
+
+MIT © yshengliao —— 見 [LICENSE](LICENSE)。