aispritejs 0.1.0

package/llms-full.txt

@@ -0,0 +1,449 @@
+# aispritejs — full LLM context
+
+This file is auto-generated by `scripts/build-llms-full.mjs`. Do not edit
+manually; instead edit the underlying source documents and re-run the
+script. The file concatenates the canonical English documentation surface
+so an LLM agent can ingest the full project context in a single fetch.
+
+The short index lives at `llms.txt` (see https://llmstxt.org/).
+
+---
+
+<!-- ===== README.md ===== -->
+
+# 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).
+
+---
+
+<!-- ===== CHANGELOG.md ===== -->
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-03
+
+Initial release — the input-driven core plus the PixiJS v8 adapter, atlas
+parser, and JSON Schema (roadmap modules 1–4).
+
+### Added
+
+- **`createSpriteAnimator(graph)`** — the public factory returning a
+  `SpriteAnimator`. No exported class constructor (family convention: public
+  API = `createX`). Implemented as closures, so methods never depend on `this`.
+- **Inputs** — three kinds driving the visual state machine:
+  - `Number` (continuous, e.g. `speed`) and `Boolean` (toggle, e.g.
+    `isGrounded`), set via `setInput(name, value)`.
+  - `Trigger` (one-shot, e.g. `jump`), fired via `fireTrigger(name)`; stays
+    pending across frames until a transition consumes it.
+  - O(1) lookup; unknown names throw `UnknownInputError`, kind mismatches throw
+    `InputTypeError`, and `NaN` is rejected.
+- **Transition graph** — `StateDef` (animation key + `loop` / `onEnd` / `speed`),
+  `TransitionCondition` (`Equals` / `NotEquals` / `GreaterThan` / `LessThan` /
+  `Trigger`), and `TransitionDef` with **Any-State** (`from: "*"`) and integer
+  `priority`. Resolution is deterministic: highest priority then declared order,
+  taking the first *effective* transition. A self-targeting transition is
+  effective only if it consumes a Trigger (a Number/Boolean self-loop cannot
+  restart the clip every frame).
+- **`update(deltaMs)`** — advances the timer by `dt × speed` (negative `dt`
+  clamps to `0`), evaluates transitions, computes the active frame from
+  cumulative per-frame durations + loop, and fires `onComplete` once for a
+  finished non-looping clip followed by any `onEnd` auto-transition. No
+  per-frame allocation.
+- **Outputs** — `activeState`, `activeFrameKey`, `activeFrameIndex` for renderer
+  adapters.
+- **Typed emitters** — `onStateChange((to, from) => …)` and
+  `onComplete((state) => …)`, each returning an unsubscribe and accepting
+  `{ signal, once }`. Own minimal implementation; **does not** import
+  `aieventjs` or any sibling.
+- **Lifecycle** — `reset()` returns to the initial state and restores input
+  defaults without releasing buffers (fires `onStateChange` only if the state
+  changed); `dispose()` is idempotent and makes subsequent mutators throw
+  `SpriteAnimatorDisposedError`.
+- **Fail-fast validation** — `createSpriteAnimator` validates every
+  cross-reference the type system cannot (missing animation, unknown transition
+  target, operator/kind compatibility, positive durations and speed, `onEnd`
+  vs `loop`) and throws `InvalidGraphError`.
+- **Atlas-shaped input** — the graph consumes PixiJS-v8-native `animations` /
+  `frames` blocks (only frame keys + `duration` are read by the core),
+  augmented with the `aispritejs` `inputs` / `states` / `transitions` block. A
+  foreign event-driven `states` block is ignored.
+- **Docs** — README (canonical) + `README_ZHTW.md`, `STABILITY.md`,
+  `CONTRIBUTING.md`, `ROADMAP.md`, `llms.txt` / `llms-full.txt`, and a runnable
+  Node example (`examples/01-platformer-inputs`).
+
+### Added — `aispritejs/pixi` adapter
+
+- **`createPixiSpriteAnimator(sprite, graph, textures, options?)`** on the
+  `aispritejs/pixi` subpath — binds the renderer-agnostic core to a PixiJS v8
+  `Sprite`. On each `update(dt)` it runs the core machine and, when the active
+  frame changes, swaps the sprite's texture and applies that frame's atlas
+  anchor (`texture.defaultAnchor`) — preserving non-centre / foot pivots
+  (`{ applyAnchor: false }` opts out). Accepts a `Spritesheet` or a frame-key →
+  `Texture` map.
+- **`MissingTextureError`** — fail-fast at construction when a frame key the
+  graph references has no texture (carries `.keys`).
+- `pixi.js` declared as an **optional** `peerDependency`
+  (`peerDependenciesMeta.optional`). The adapter imports it **type-only**, so
+  the built subpath contains no runtime `pixi.js` require; the core never
+  imports the adapter.
+- Guard: if a *playing* `AnimatedSprite` is passed (it extends `Sprite`), its
+  internal playback is stopped on bind so its ticker cannot fight the adapter's
+  texture swaps. The adapter expects a plain `Sprite`.
+
+### Added — `aispritejs/atlas` parser + JSON Schema
+
+- **`parseAtlas(atlas, control?)`** and **`loadAtlas(atlas, control?)`** on the
+  `aispritejs/atlas` subpath — turn a parsed PixiJS-v8 atlas into a
+  `SpriteGraph` (or a ready `SpriteAnimator`). The atlas supplies the universal
+  `animations` / `frames`; the input-driven control comes from the atlas itself
+  (augmented shape) or from the `control` argument.
+- **Ignores a foreign event-driven `states` block** — the FSM `{ initial,
+  definitions }` shape emitted by other tools is detected and skipped; pass an
+  `aispritejs` control block instead. Verified against the real family pipeline
+  atlas (`test/fixtures/reimu-atlas.json`).
+- **`InvalidAtlasError`** for structural problems (fail-fast); semantic problems
+  surface as `InvalidGraphError` from the core.
+- **JSON Schema** shipped at `schemas/aispritejs-graph.schema.json` (draft
+  2020-12), exported as `aispritejs/schema`, describing the input-driven graph.
+  The parser mirrors it in code, so there is no runtime schema-validator
+  dependency.
+
+### Guarantees (CI)
+
+- Strict TypeScript (`strict` + `noUncheckedIndexedAccess` +
+  `exactOptionalPropertyTypes`), no `any`.
+- Dual ESM + CJS build via `tsup`; `sideEffects: false`; `.` + `/pixi` +
+  `/atlas` + `/schema` subpath exports; per-subpath gzip budgets.
+- **Zero runtime dependencies**; the root import graph contains no `pixi.js`,
+  DOM, or canvas API.
+- `prepublishOnly` gate: typecheck → lint → coverage → build → verify:exports →
+  verify:llms → check:size. Coverage at 100 % statements / branches / functions
+  / 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.0...HEAD
+[0.1.0]: https://github.com/yshengliao/aispritejs/releases/tag/v0.1.0
+
+---
+
+<!-- ===== CONTRIBUTING.md ===== -->
+
+# Contributing to aispritejs
+
+Thanks for helping improve `aispritejs` — the input-driven, renderer-agnostic
+sprite animation runtime in the **ai\*js** family.
+
+## Quick start
+
+```bash
+pnpm install
+pnpm test                 # vitest, run once
+pnpm coverage             # with thresholds
+pnpm typecheck            # tsc --noEmit (strict)
+pnpm lint                 # biome check src test
+pnpm build                # tsup → ESM + CJS + .d.ts
+pnpm example:platformer   # runnable Node demo
+```
+
+The full pre-publish gate (also run in CI) is:
+
+```bash
+pnpm typecheck && pnpm lint && pnpm coverage && pnpm build \
+  && pnpm verify:exports && pnpm verify:llms && pnpm check:size
+```
+
+If you edit any of `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, or
+`examples/README.md`, regenerate the bundled LLM context and commit it:
+
+```bash
+pnpm build:llms   # writes llms-full.txt; verify:llms fails CI if it drifts
+```
+
+## What gets in easily
+
+- Bug fixes with a regression test.
+- More renderer adapters behind their own subpath (each importing its renderer
+  as an **optional** `peerDependency`, never from the core).
+- Docs, examples, and test coverage.
+
+## What needs discussion first
+
+- Any change to the **public API** (the `createSpriteAnimator` surface or the
+  graph data format) — open an issue. The API freezes at 1.0.0.
+- A new control model or operator — the input-driven model (Number / Boolean /
+  Trigger) is deliberate; see the Rive comparison in the README.
+
+## Design principles (non-negotiable)
+
+- **Renderer-agnostic core.** `src/index.ts` and everything it imports must not
+  touch `pixi.js`, the DOM, or any canvas API. Only adapter subpaths may.
+- **Zero cross-package imports.** Never import `aifsmjs`, `aieventjs`,
+  `aiplaybook`, or any sibling. Ship your own minimal code.
+- **Input-driven, not event-driven.** This is a *visual* animator, not a
+  game-logic FSM (that is `aifsmjs`). Make no assumption about the logic layer.
+- **Deterministic & allocation-free.** Identical input + `dt` sequences must
+  produce identical frames; the no-transition `update` path allocates nothing.
+- **Fail-fast.** Validate graphs and inputs eagerly with named errors.
+- **`createX` factories, never bare constructors.** `dispose()` is idempotent;
+  subscriptions return an unsubscribe and accept `{ signal, once }`.
+- **Domain-neutral surface.** No game nouns (`player`, `score`, …) in the public
+  API; `idle` / `walk` / `jump` only as examples.
+
+## Commit & PR style
+
+- Conventional-commit subjects (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
+- End commit messages with a `Co-Authored-By:` trailer for the model that wrote
+  them.
+- Keep PRs focused; update `CHANGELOG.md` under `[Unreleased]`.
+- Do not bump the version or push tags in a PR — releases are cut by the
+  maintainer (the publish workflow runs on tag-push via OIDC).
+
+---
+
+# Examples index (`examples/README.md`)
+
+# Examples
+
+Runnable, renderer-free demonstrations of the `aispritejs` core. Each runs in
+plain Node via `tsx` — no canvas, no PixiJS — and logs the active state and
+frame key as inputs drive the visual state machine.
+
+## 01 — platformer inputs
+
+```bash
+pnpm example:platformer
+```
+
+[`01-platformer-inputs/index.ts`](examples/01-platformer-inputs/index.ts) wires a
+classic `idle` / `walk` / `jump` graph and exercises every core idea:
+
+- a **Number** input (`speed`) drives `idle ⇄ walk`;
+- a **Trigger** (`jump`) fires an **Any-State** transition that beats `walk` by
+  `priority`, is consumed on use, and is one-shot;
+- a **Boolean** (`isGrounded`) is set alongside, showing inputs are independent
+  of the transitions that read them;
+- `jump` is non-looping with `onEnd: "idle"`, so the clip auto-returns to
+  `idle` and fires `onComplete`;
+- `onStateChange` / `onComplete` subscriptions log the transitions;
+- `update(dt)` advances per-frame timing; `dispose()` tears down.
+
+The same `graph` object would drive a PixiJS sprite unchanged via the
+`aispritejs/pixi` adapter — the core never knows a renderer exists.
+
+---

package/llms.txt

@@ -0,0 +1,40 @@
+# aispritejs
+
+> Input-driven, renderer-agnostic 2D sprite animation runtime — a tiny, Rive-like *visual* state machine. Developers set runtime inputs (`Number` / `Boolean` / `Trigger`); a JSON transition graph decides which animation frame is on screen. The core is pure TypeScript with zero runtime dependencies and never imports `pixi.js`, the DOM, or any canvas API. Bind it to a renderer (PixiJS v8, etc.) through a thin adapter. Browser / Node / Bun / Deno / WebView / Worker friendly.
+
+Primary audience: developers building browser-based games and interactive web experiences who want to decouple *visual* animation state from game logic. You set parameters like `speed=4`, `isGrounded=false`, `fireTrigger("jump")`; `aispritejs` picks the visual state and ticks the active frame. It is a complement to — never a dependency of — a game-logic FSM such as `aifsmjs` (event-driven); here the model is input-driven, like Rive, but sprite-atlas based with no wasm runtime.
+
+Key guarantees: deterministic `update(dt)` (identical inputs + Δt ⇒ identical frames); no per-frame allocation; named errors (`InvalidGraphError`, `UnknownInputError`, `InputTypeError`, `SpriteAnimatorDisposedError`) instead of bare throws; public API is the `createSpriteAnimator` factory (no exported class constructor); `dispose()` idempotent, `reset()` keeps buffers, subscriptions return an unsubscribe and accept `{ signal, once }`; own minimal typed emitter (does NOT import `aieventjs`); `sideEffects: false`; core gzip ≈ 3.5 KB.
+
+## Documentation
+
+- [README.md](README.md): canonical English README — Why, Mental Model, Core API, Semantics (the precise rules), Errors, Decoupling, Comparison, AI-Agent Reading Guide, Testing, Status, Roadmap.
+- [README_ZHTW.md](README_ZHTW.md): Traditional Chinese mirror of the canonical README.
+- [ROADMAP.md](ROADMAP.md): phased plan (v0.1.0 core → v0.2.0 PixiJS adapter → v0.3.0 atlas parser + JSON Schema → 1.0 freeze) and design invariants.
+- [STABILITY.md](STABILITY.md): stability tier of every public symbol plus the pinned behavioural contract.
+- [CHANGELOG.md](CHANGELOG.md): Keep a Changelog format; the 0.1.0 entry covers the core surface and CI guarantees.
+- [CONTRIBUTING.md](CONTRIBUTING.md): quick-start commands, design principles, commit & PR style.
+- [llms-full.txt](llms-full.txt): README + CHANGELOG + CONTRIBUTING + examples index concatenated into one file — load this when an AI agent needs the full context in a single fetch.
+
+## Source layout
+
+- [src/index.ts](src/index.ts): root barrel — re-exports the `sprite/` core. Imports no renderer.
+- [src/sprite/types.ts](src/sprite/types.ts): every public type in one file (`SpriteGraph`, `InputDef`, `StateDef`, `TransitionDef`, `TransitionCondition`, `SpriteAnimator`, handlers).
+- [src/sprite/machine.ts](src/sprite/machine.ts): `createSpriteAnimator` — the input-driven engine (`setInput` / `fireTrigger` / `update` / `reset` / `dispose`, `onStateChange` / `onComplete`, `activeState` / `activeFrameKey` / `activeFrameIndex`).
+- [src/sprite/compile.ts](src/sprite/compile.ts): graph validation + normalisation into precomputed, allocation-free runtime form (per-state cumulative timings; per-state transition candidate lists sorted by priority then declared order).
+- [src/sprite/inputs.ts](src/sprite/inputs.ts): O(1) input store (Number/Boolean values + Trigger pending flags) with default-reset.
+- [src/sprite/emitter.ts](src/sprite/emitter.ts): the package's own minimal typed signal with `{ signal, once }` — no `aieventjs` import.
+- [src/sprite/errors.ts](src/sprite/errors.ts): the four named error classes.
+- [src/pixi/animator.ts](src/pixi/animator.ts): the `aispritejs/pixi` adapter — `createPixiSpriteAnimator(sprite, graph, textures, options?)` swaps a PIXI.Sprite's texture to the active frame and applies the atlas anchor. Imports `pixi.js` **type-only** (optional peer); the core never imports it. Subpath: `aispritejs/pixi`.
+- [src/atlas/parse.ts](src/atlas/parse.ts): the `aispritejs/atlas` parser — `parseAtlas(atlas, control?)` / `loadAtlas(atlas, control?)` turn a PixiJS-v8 atlas into a `SpriteGraph` / `SpriteAnimator`, ignoring any foreign event-driven `states` block. `InvalidAtlasError`, `SpriteControl`. Pure, zero-dependency. Subpath: `aispritejs/atlas`. JSON Schema at [schemas/aispritejs-graph.schema.json](schemas/aispritejs-graph.schema.json), exported as `aispritejs/schema`.
+
+## Examples
+
+- [examples/01-platformer-inputs/index.ts](examples/01-platformer-inputs/index.ts): a renderer-free `idle` / `walk` / `jump` graph — a Number drives idle⇄walk, a Trigger fires an Any-State jump that beats walk by priority and is one-shot, `jump` auto-returns to idle via `onEnd`. Run with `pnpm example:platformer`.
+
+## Quality gates
+
+- [.github/workflows/ci.yml](.github/workflows/ci.yml): Node 20 + 22 matrix; typecheck, lint (biome), coverage (vitest + @vitest/coverage-v8 at 95/90/100/100 thresholds, met at 100% across the board), build (tsup → ESM + CJS + .d.ts), exports verification, size budget, and llms drift check.
+- [scripts/check-size.mjs](scripts/check-size.mjs): per-subpath gzip budget (core ≤ 3.8 KB; `aispritejs/pixi` ≤ 4.2 KB, pixi.js external; `aispritejs/atlas` ≤ 4.4 KB, zero-dependency).
+- [scripts/verify-exports.mjs](scripts/verify-exports.mjs): asserts every `package.json#exports` entry resolves to a real file in `dist/`.
+- [.github/workflows/publish.yml](.github/workflows/publish.yml): OIDC trusted-publisher + provenance on tag-push.

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "aispritejs",
+  "version": "0.1.0",
+  "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",
+    "animation",
+    "sprite-animation",
+    "state-machine",
+    "rive",
+    "input-driven",
+    "game-dev",
+    "web-game",
+    "pixijs",
+    "atlas",
+    "spritesheet",
+    "ai-readable",
+    "typescript",
+    "esm"
+  ],
+  "author": "yshengliao",
+  "license": "MIT",
+  "homepage": "https://github.com/yshengliao/aispritejs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yshengliao/aispritejs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yshengliao/aispritejs/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./pixi": {
+      "types": "./dist/pixi/index.d.ts",
+      "import": "./dist/pixi/index.js",
+      "require": "./dist/pixi/index.cjs"
+    },
+    "./atlas": {
+      "types": "./dist/atlas/index.d.ts",
+      "import": "./dist/atlas/index.js",
+      "require": "./dist/atlas/index.cjs"
+    },
+    "./schema": "./schemas/aispritejs-graph.schema.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md",
+    "README_ZHTW.md",
+    "LICENSE",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "peerDependencies": {
+    "pixi.js": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pixi.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "fast-check": "^4.8.0",
+    "pixi.js": "^8.18.1",
+    "tsup": "^8.3.0",
+    "tsx": "^4.22.3",
+    "typescript": "^5.6.0",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src test",
+    "format": "biome format --write src test",
+    "typecheck": "tsc --noEmit",
+    "verify:exports": "node scripts/verify-exports.mjs",
+    "check:size": "node scripts/check-size.mjs",
+    "build:llms": "node scripts/build-llms-full.mjs",
+    "verify:llms": "node scripts/build-llms-full.mjs --check",
+    "coverage": "vitest run --coverage",
+    "example:platformer": "tsx examples/01-platformer-inputs/index.ts"
+  }
+}