feat(pbs): add sprite animation and shared Studio authoring

Implement DEC-0084 with factory-only Sprite/Animator structs, complete result
lowering, validated animation sidecars, generated PBS factories and JavaFX/MCP
authoring through shared services.

Qualify native dev/release with ordinary and optimized producers, zero-allocation
playback, private-cycle reclamation, canonical Composer pixels, installed JARs
and JavaFX lifecycle. Preserve the runtime checkout and existing host ABI.
This commit is contained in:
2026-11-05 15:16:07 +00:00
parent 1d8b8c2101
commit bf31184d4d
151 changed files with 4823 additions and 98 deletions
@@ -0,0 +1,142 @@
# Animation Authoring Specification
Status: Normative v1. Owner: studio. PBS projection owner: compiler/pbs.
Packer owns registered assets, composition, effective glyph indices and fingerprints.
## Purpose
JavaFX, AI tools and compiler consumers share one versioned editorial document,
validator and bank-layout identity contract. This sidecar is neither a runtime
asset nor generated editable PBS. The entire authoring/projection contract is
specified below.
## Canonical document and services
Each registered glyph bank can contain animations.studio.json, a JSON UTF-8
sidecar distinct from asset.json and studio.asset.json. Its strict schema is:
```json
{
"schema_version": 1,
"bank_asset_uuid": "<containing bank UUID>",
"bindings": [{"artifact_id": "<stable selected artifact>", "glyph_id": 7,
"fingerprint": "<sha256>"}],
"animators": [{"id": "hero", "initial_clip": "idle", "clips": [
{"name": "idle", "mode": "loop", "frames": [
{"artifact_id": "<stable selected artifact>", "duration_ticks": 4}
]}
]}]
}
```
Animator IDs are unique PBS identifiers matching [A-Za-z_][A-Za-z0-9_]*. Modes
are once/loop; frame order matters. Each animator has nonempty named clips;
zero animator definitions is allowed. Decode long integers exactly. No palette,
position or runtime bank slot is stored. Unknown fields/versions and malformed
or duplicate bindings/JSON keys are errors, not fallback triggers.
Every referenced artifact must match the containing bank UUID and Packer's current
effective glyph ID/fingerprint. Reordering, removal and content replacement produce
blocking drift diagnostics. Explicit prepare/apply rebind presents old/new bindings
and affected frames, validates the result and requires the expected revision.
Never silently retarget by list order or path. Save validates the whole candidate
against the current snapshot and uses a revision check plus atomic replacement;
failed validation/conflict preserves the canonical file and editable draft.
Perform revision verification and publication under the same project exclusion;
replace atomically within the same filesystem. Read/validate may expose an invalid
document with diagnostics for repair; preview/build/projection must not fall back
to an older valid document or another schema version.
The new neutral prometeu-animation library (p.animation) owns immutable DTOs,
strict codec, shared validator, revisions and editorial preview timeline. It has
no JavaFX/Spring/compiler/concrete-packer dependency. Packer exposes effective
layout snapshots, and app supplies the neutral GlyphBankLayoutSource port. Both
Studio services and the build context loader use this shared validator. A build
with included definitions but no configured resolver fails explicitly. Existing
projects without definitions retain an empty context and compatible entry points.
FESurfaceContext carries language-neutral validated snapshots; PBS alone emits
virtual modules at @<project-name>:generated/animations/b_<uuid-without-hyphens>.
Factories are create_<animator_id>(bank_id: int) -> result<AnimationError> Animator.
Reserve generated/animations and reject physical-module collisions. Only registered,
build-included banks publish factories. Invalid included definitions block build;
never reuse stale generated text. Sort factories by ID, preserve clip/frame order,
escape PBS literals and exclude timestamps/absolute paths. Keep generated modules
read-only through FrontendSourceDocument and revision-scoped ExternalSourceRegistry
URIs, with generated spans mapped to original JSON fields. No generated source
becomes a second editable persistence surface.
Generated revision includes the document, resolved bindings and generator version.
Invalidate old origins after changes/reconnect, reject generated save/rename, and
let the UI open the original JSON field through the authoring service.
Studio API/core provides list/read, draft validation, save/delete, prepare/apply
rebind and preview. JavaFX provides complete animator/clip/frame authoring, initial
clip/mode, durations, ordering, diagnostics, save and drift repair. Preview has
play/pause, explicit ticks and palette input. Shared neutral rendering returns
canonical image plus observed bank/glyph/state/ticks; its timeline must match PBS
native execution. No palette/position is persisted in the animation definition.
MCP adds task-authorized studio_animation_query (list/get/validate/preview) and
studio_animation_update (save/delete/prepare_rebind/apply_rebind), with strict
schemas, expected revisions and the same services as UI. Reuse existing authority,
operations, cancellation, revocation, conflict handling and document handoff.
Both tools take projectRoot, taskId and operation, plus these exact domain fields:
| Operation | Fields and behavior |
| --- | --- |
| query/list | Optional assetUuid filter; project definitions/diagnostics. |
| query/get | assetUuid; current document, revision, diagnostics. |
| query/validate | assetUuid, optional candidate document; no persistence. |
| query/preview | assetUuid, animatorId, clipName, nonnegative long elapsedTicks, paletteId, optional candidate document; sample from clip start. |
| update/save | assetUuid, expectedRevision, complete document; explicit null revision only for create, never overwrite an existing file on create. |
| update/delete | assetUuid, expectedRevision, animatorId; preserve other definitions. |
| update/prepare_rebind | assetUuid, expectedRevision; return diff, candidate document/hash and bank snapshot revision, without writing. |
| update/apply_rebind | assetUuid, expectedRevision, document, proposalHash, expectedBankRevision; validate the same proposed binding-only change against the current bank. |
Reject fields belonging to a different operation. Use the existing typed result
envelope and image contract. Proposal hashes correlate content, not a new grant or
approval workflow. UI autoplay schedules explicit tick updates with a transient
preview rate; preview never persists an animation clock.
## Persistence and authority
Operations use project identity, asset UUID, animator ID and expected revision;
arbitrary caller-provided file paths are not definition addresses. Resolve authority
before cache lookup. Manual, Agent and Debug use existing project exclusion,
cancellation/revocation and document handoff; no parallel grant or approval flow
is introduced. Save validates the whole document against the current layout,
checks expected revision under project exclusion and atomically replaces the file
on the same filesystem. Conflict or recoverable failure preserves canonical bytes
and the editable draft.
Rebind is the only binding migration operation: preparation returns old/new IDs,
fingerprints and affected frames without persisting; application validates the
same proposal hash, document revision and bank revision before replacement.
Read, preview, analysis and build never silently repair or reuse stale sources.
## Preview and UI
The editor integrates glyph-bank details and supports create/rename/delete of
animators and clips, initial-clip/mode selection, frame addition/removal/reordering,
exact long-duration entry, diagnostics, save conflicts and explicit drift repair.
Palette and position are transient viewing inputs. Play schedules explicit ticks
using a transient preview rate; no clock is persisted in animation definitions.
The renderer returns canonical pixels and observed bank/glyph/state/ticks without
JavaFX and must reject invalid bank/references instead of simulating success.
The timeline follows the complete state/interval table in
[Core Sprite and Animation](../compiler-languages/pbs/27.%20Core%20Sprite%20and%20Animation%20Specification.md).
Production-native conformance must compare those observations for identical input
timelines, direct/generated factories and both producer/runtime profiles.
## Dependencies and distribution
`prometeu-animation` (`p.animation`) contains immutable DTOs, strict JSON codec,
structural/snapshot validation, revisions and preview timeline. It depends on no
JavaFX, Spring, HTTP, compiler or concrete Packer implementation. Studio core
orchestrates persistence/layout/rendering; app composes the Packer API adapter.
PBS alone generates PBS source; compiler/backend stay independent of Studio core.
Installed references, examples and MCP schemas must expose this same contract.