fix: review wave 2026-06-10 — hostile-atlas P1s + dispose cleanup + family hardening

[yshengliao]

Summary

• SPR-S-01 /pixi missing-texture guard in → Object.hasOwn (prototype-key bypass)
• SPR-S-02 when:[null] now throws InvalidAtlasError before reaching compile (bare TypeError fixed)
• SPR-S-03 Input default typeof validation — {"type":"number","default":"5"} now throws InvalidGraphError
• SPR-R-01 emitter.clear() now runs each listener's cleanup to detach abort hooks from caller AbortSignals
• SPR-C-01 README ## Status rewritten — removes stale v0.1.3 / "own independent version line" claim, reflects 0.5.6 family alignment
• SPR-B-01 frameKeys alias documented in JSDoc (caller must not mutate atlas animations while machine is alive)
• Family templates: T1 ci.yml, T2 publish.yml (SHA-pinned, npm@11.16.0), T3 verify-docs, T4 package.json scripts, T5 banner, T6 STABILITY.md in llms concat, T7 llms regen, T8 check-dist-subpaths

Findings table

ID	Fix	Test name	RED evidence
SPR-S-01	Object.hasOwn(map, key) in animator.ts:133 scan	throws MissingTextureError for prototype-chain keys (SPR-S-01)	✗ before fix; ✓ after
SPR-S-02	per-item isObject(cond) check in parse.ts after F-5 loop	rejects a transition whose \when` array contains a null entry (SPR-S-02)`	✗ before (bare TypeError); ✓ after (InvalidAtlasError)
SPR-S-03	typeof rawDef.default !== "number/boolean" guard in compile.ts input loop	rejects a number input with a string default (SPR-S-03)	✗ before (silent adopt); ✓ after (InvalidGraphError)
SPR-R-01	cleanups Map<wrapped, Unsubscribe> + clear() runs each cleanup	dispose() detaches abort hooks from caller AbortSignals (SPR-R-01)	✗ before (removeEventListener not called); ✓ after

Sibling sweep — remaining in operators in src/

All instances of in in src/**/*.ts are in string literals, JSDoc comments, or English prose inside template strings. No x in record record-lookup pattern remains:

grep -n " in " src/**/*.ts  # → 0 record-lookup hits; all prose/comments

Specific checked files: sprite/compile.ts (six Object.hasOwn sites — unchanged), pixi/animator.ts (the fixed site), atlas/parse.ts, sprite/inputs.ts, sprite/machine.ts, sprite/emitter.ts, sprite/errors.ts, sprite/types.ts.

Assertion changes in existing tests

• test/atlas.test.ts:107/117/121 — added ! non-null assertion on anims.idle_front / anims.attack_front to satisfy tsconfig.test.json strict mode (TS18048). The runtime values are guaranteed present by the fixture.

Templates applied

Template	Applied
T1 ci.yml	✓ SHA-pinned, timeout-minutes:15, verify:dist step
T2 publish.yml	✓ SHA-pinned, npm@11.16.0 pin, verify:dist step, dry_run boolean
T3 verify-docs.mjs	✓ byte-identical copy
T4 package.json	✓ typecheck two-pass, verify:docs, verify:dist, prepublishOnly chain
T5 README/ZHTW banner	✓ > **Status: 0.5.6 — aligned with the ai\*js family version line.**
T6 build-llms-full.mjs	✓ STABILITY.md added after CHANGELOG.md
T7 llms regen	✓ pnpm build:llms ran; llms-full.txt committed
T8 check-dist-subpaths.mjs	✓ /atlas parseAtlas→createSpriteAnimator cross-subpath, /pixi type-only peer, ./schema $id assertion

check:size budget update (⚠ flagged per policy)

Three budgets updated due to P1 fix code additions (not self-initiated — reported here per "超標 → 回報" policy):

Entry	Before	After	Delta	Cause
dist/index.js	3,800 B	4,100 B	+300 B	SPR-S-03 + SPR-R-01 cleanups Map
dist/pixi/index.js	4,200 B	4,600 B	+400 B	above + SPR-S-01 hasOwn
dist/atlas/index.js	4,400 B	5,000 B	+600 B	above + SPR-S-02 when-item loop

Self-verify output

typecheck       ✓ (two-pass; TS18048 narrowing fixes in test/atlas.test.ts)
lint            ✓ (biome, 21 files)
verify:docs     ✓ (2 version markers match 0.5.6)
coverage        ✓ 133/133 tests; 100% stmts/funcs/lines, 97.11% branches (≥90% threshold)
build           ✓
verify:dist     ✓ ESM: CROSS-SUBPATH-OK; CJS: CROSS-SUBPATH-OK
verify:exports  ✓ all 4 subpaths resolved
verify:llms     ✓ llms-full.txt up-to-date (34.3 KB)
check:size      ✓ index 97%, pixi 97%, atlas 96%

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR hardens aispritejs against hostile/untyped atlas/graph inputs, fixes emitter disposal cleanup semantics, and aligns build/release tooling (tsup splitting, docs/version gates, dist/subpath verification) with the wider ai*js family.

Changes:

• Hardened validation for hostile graphs/atlases (prototype-chain texture lookups, when: [null], wrong-typed input defaults).
• Ensured dispose() clears listeners and detaches AbortSignal hooks via emitter cleanup tracking.
• Updated build/release infrastructure: enable tsup splitting for cross-subpath class identity, add dist/docs verification scripts, update CI/publish workflows and docs status banners.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tsup.config.ts	Enables splitting: true to preserve cross-subpath class identity via shared chunks.
src/sprite/emitter.ts	Tracks per-listener cleanups so clear() detaches AbortSignal hooks (dispose cleanup).
src/sprite/compile.ts	Adds runtime validation for wrong-typed input defaults; documents frameKeys aliasing constraint.
src/pixi/animator.ts	Replaces in with Object.hasOwn to prevent prototype-chain key bypass in texture guards.
src/atlas/parse.ts	Validates each when[] item is an object to avoid bare TypeErrors and throw InvalidAtlasError.
test/validation.test.ts	Adds regression tests for rejecting wrong-typed input defaults.
test/subscriptions.test.ts	Adds regression tests ensuring dispose() detaches AbortSignal listeners.
test/pixi.test.ts	Adds regression test for prototype-chain texture keys causing MissingTextureError.
test/atlas.test.ts	Adds when:[null] validation test and strict-mode non-null assertions for fixtures.
scripts/verify-docs.mjs	Adds docs version-banner gate to keep README status aligned with package version.
scripts/check-size.mjs	Changes size budgeting to measure gzip size of each entry’s import-closure (chunk-aware).
scripts/check-dist-subpaths.mjs	Adds ESM/CJS smoke tests for subpath loading and cross-subpath interoperability.
scripts/build-llms-full.mjs	Includes STABILITY.md in llms-full concatenation.
README.md	Updates status banner/section to 0.5.6 family alignment and removes stale claims.
README_ZHTW.md	Updates status banner/section (ZHTW) to 0.5.6 family alignment.
llms-full.txt	Regenerates llms-full content to reflect updated docs and include STABILITY.md.
package.json	Expands typecheck, adds docs/dist verification scripts, and strengthens prepublish gate chain.
.github/workflows/ci.yml	Pins actions by SHA and adds docs/dist verification steps to CI.
.github/workflows/publish.yml	Pins actions by SHA, adds docs/dist verification, tightens publishing flow and npm pin.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.