aispritejs 0.5.5 → 0.5.7

package/llms-full.txt

@@ -14,7 +14,7 @@ The short index lives at `llms.txt` (see https://llmstxt.org/).
 # 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)
+[![CI](https://github.com/islumina/aispritejs/actions/workflows/ci.yml/badge.svg)](https://github.com/islumina/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-Claude_Code_Opus_4.8-blueviolet.svg)](https://www.anthropic.com/claude-code)
 [![繁體中文](https://img.shields.io/badge/lang-繁體中文-red.svg)](README_ZHTW.md)
@@ -25,6 +25,8 @@ The short index lives at `llms.txt` (see https://llmstxt.org/).
 
 Part of the **ai\*js** family: zero cross-package dependencies, framework-agnostic core, AI-readable docs.
 
+> **Status: 0.5.7 — aligned with the ai\*js family version line.** Renderer-agnostic core plus `/pixi`, `/atlas`, `/schema` subpaths; hardened atlas/graph validation. See [CHANGELOG.md](CHANGELOG.md) for history.
+
 ## 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.
@@ -269,9 +271,7 @@ pnpm example:explosion   # 6-frame play-once FX via the /pixi adapter
 
 ## Status
 
-**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.
+**Aligned with the ai\*js family version line.** The package version is synchronised with the shared family version (`0.5.x` — the banner above and [CHANGELOG.md](CHANGELOG.md) carry the exact release). All four roadmap modules are live: the renderer-agnostic core (`.`), the PixiJS v8 adapter (`aispritejs/pixi`), the atlas parser (`aispritejs/atlas`), and the JSON Schema (`aispritejs/schema`). Prior hardening waves delivered compile-time rejection of non-finite `speed` / `duration` / `defaultFrameDuration`, runtime clamping of non-finite or non-positive `dt` to `0` in `update()`, and named-error coverage for hostile atlas shapes. 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.
 
 ## Roadmap
 
@@ -294,6 +294,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.7] - 2026-06-10
+
+### Fixed
+
+- **`/pixi` adapter prototype-key lookup** — the missing-texture guard now uses `Object.hasOwn` instead of the `in` operator (mirroring the core's 0.5.x hasOwn fixes), so atlas frame keys like `"constructor"` / `"toString"` no longer resolve through `Object.prototype`. (Review wave 2026-06-10, SPR-S-01.)
+- A `when` array containing `null` / non-object entries is rejected by `parseAtlas` with `InvalidAtlasError` instead of crashing later in compilation with a bare `TypeError`. (SPR-S-02.)
+- An input `default` whose runtime type contradicts the declared `type` (e.g. `{ "type": "number", "default": "5" }`) is rejected with `InvalidGraphError` instead of being silently adopted into the input store. (SPR-S-03.)
+- The internal signal's `clear()` (and therefore `dispose()`) now runs each listener's cleanup, detaching abort hooks from caller-owned `AbortSignal`s — a long-lived signal no longer accumulates dead listeners. (SPR-R-01.)
+
+### Changed
+
+- **Code splitting enabled (`tsup splitting: true`)** — each subpath bundle previously inlined its own copy of the shared core, so an `InvalidGraphError` thrown via `aispritejs/atlas`'s `loadAtlas` failed `instanceof` checks against the root export. Shared chunks restore cross-subpath class identity; the new `verify:dist` smoke asserts it (ESM + CJS). `check:size` now measures each entry's transitive chunk closure (index 4,175 / pixi 4,852 / atlas 5,216 B gzip measured; ~350 B of that is this wave's validation/cleanup code).
+- Supply-chain and release hardening: CI/publish actions SHA-pinned, npm CLI pinned (`11.16.0`), `permissions: contents: read` on CI, job timeouts, `npm publish --ignore-scripts`, manual dispatch defaults to dry-run, new `verify:docs` banner gate, two-stage typecheck (tests are now type-checked), `llms-full.txt` embeds `STABILITY.md`.
+
+### Docs
+
+- README `## Status` section rewritten: the version line now tracks the ai\*js family (the previous "own independent version line" claim was stale); normalised status banners added (EN + ZHTW); the compiled state's `frameKeys` alias contract documented (don't mutate atlas animations while a machine is live).
+
+## [0.5.6] - 2026-06-09
+
+### Added
+
+- `PixiSpriteAnimator` now exposes `onComplete` / `onStateChange`, delegating directly to the core animator.
+
 ## [0.5.5] - 2026-06-08
 
 ### Changed
@@ -433,12 +457,74 @@ 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/islumina/aispritejs/compare/v0.5.5...HEAD
+[Unreleased]: https://github.com/islumina/aispritejs/compare/v0.5.6...HEAD
+[0.5.6]: https://github.com/islumina/aispritejs/compare/v0.5.5...v0.5.6
 [0.5.5]: https://github.com/islumina/aispritejs/releases/tag/v0.5.5
-[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
+[0.1.3]: https://github.com/islumina/aispritejs/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/islumina/aispritejs/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/islumina/aispritejs/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/islumina/aispritejs/releases/tag/v0.1.0
+
+---
+
+<!-- ===== STABILITY.md ===== -->
+
+# Stability
+
+This document defines the stability tier of every public symbol exported by
+`aispritejs`. Tiers govern what breaks may occur in future minor / major bumps.
+The public API freezes at 1.0.0.
+
+## Stable (since 0.1.0)
+
+Fully stable. Breaking changes only at a major version bump (1.0+).
+
+- **Factory** — `createSpriteAnimator(graph)`.
+- **`SpriteAnimator` methods** — `setInput`, `fireTrigger`, `update`, `reset`,
+  `dispose`, `onStateChange`, `onComplete`.
+- **`SpriteAnimator` accessors** — `activeState`, `activeFrameKey`,
+  `activeFrameIndex`, `disposed`.
+- **Error classes** — `InvalidGraphError`, `UnknownInputError`,
+  `InputTypeError`, `SpriteAnimatorDisposedError`.
+- **Types** — `SpriteGraph`, `InputDef` (`NumberInputDef` / `BooleanInputDef` /
+  `TriggerInputDef`), `StateDef`, `TransitionDef`, `TransitionCondition`,
+  `ConditionOp`, `FrameTiming`, `StateChangeHandler`, `CompleteHandler`,
+  `ListenerOptions`, `Unsubscribe`.
+- **`aispritejs/pixi`** — `createPixiSpriteAnimator(sprite, graph, textures,
+  options?)` binding the core to a PixiJS v8 `Sprite`, honouring per-frame
+  `duration` and the atlas `anchor` (`texture.defaultAnchor`).
+  `MissingTextureError`, `PixiSpriteAnimator`, `PixiSpriteAnimatorOptions`,
+  `TextureMap`. `pixi.js` is an **optional**, type-only `peerDependency`,
+  imported only by this subpath.
+- **`aispritejs/atlas`** — `parseAtlas(atlas, control?)`,
+  `loadAtlas(atlas, control?)`, `InvalidAtlasError`, `SpriteControl`. Consumes a
+  PixiJS-v8 atlas, ignores any foreign event-driven `states` block, and fails
+  fast. JSON Schema shipped at `schemas/aispritejs-graph.schema.json` (exported
+  as `aispritejs/schema`). Pure, zero-dependency.
+
+### Behavioural contract (stable)
+
+These semantics are part of the stable surface and are pinned by tests:
+
+- `update(dt)` order: advance `dt × speed` (negative clamps to `0`) → evaluate
+  transitions → compute frame → `onComplete` then `onEnd`.
+- Transition resolution: `priority` desc, then declared order; first *effective*
+  transition wins. A self-targeting transition is effective only if it consumes
+  a Trigger.
+- Triggers persist until consumed; one fire causes at most one transition.
+- Non-looping clips hold the last frame and fire `onComplete` exactly once;
+  looping clips wrap and never complete.
+- `defaultFrameDuration` is `100` ms; `speed` defaults to `1`.
+- Determinism: identical input + `dt` sequences ⇒ identical frame sequences.
+
+## Experimental
+
+None as of 0.1.0.
+
+## Draft (planned, not implemented)
+
+All roadmap modules (1–4) are implemented. No draft APIs outstanding; the next
+milestone is the 1.0.0 public-API freeze.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aispritejs",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "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",
@@ -66,15 +66,17 @@
     "test:watch": "vitest",
     "lint": "biome check src test",
     "format": "biome format --write src test",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "verify:docs": "node scripts/verify-docs.mjs",
     "verify:exports": "node scripts/verify-exports.mjs",
+    "verify:dist": "node scripts/check-dist-subpaths.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",
     "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"
+    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm verify:docs && pnpm coverage && pnpm build && pnpm verify:dist && pnpm verify:exports && pnpm verify:llms && pnpm check:size"
   },
   "peerDependencies": {
     "pixi.js": "^8.0.0"

package/schemas/aispritejs-graph.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/yshengliao/aispritejs/schemas/aispritejs-graph.schema.json",
+  "$id": "https://github.com/islumina/aispritejs/schemas/aispritejs-graph.schema.json",
   "title": "aispritejs input-driven sprite graph",
   "description": "The aispritejs control graph augmenting a PixiJS-v8-native atlas. The universal `animations` / `frames` blocks plus the input-driven `inputs` / `states` / `transitions`. A foreign event-driven `states` block (the FSM `{ initial, definitions }` shape) is NOT described here and is ignored by the parser. The parser mirrors these constraints in code (fail-fast); this file is the canonical spec for editors and external validation.",
   "type": "object",