Add shared human/task asset batches with reviewed atomic publication, explicit reference rebinds, ownership inspection and qualified glyph/scene budgets. Expose the same authoring and capacity results through Assets and MCP. Deliver isolated guest test targets, retained visual evidence and immutable runtime lifecycle/control observations. Preserve provider qualification and installed authoring examples alongside the completed discussion lessons. Close AGD-106 coordination and the delivered discussion workflows through housekeeping, updating lesson references and preserving qualification limits. Sound remains outside the asset delivery wave. Validation: 579 module tests and 31 additional desktop, process and installed checks passed; native glyph/scene 16/17 boundaries qualified. Discussion validation passed after housekeeping.
9.2 KiB
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:
{
"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 @:generated/animations/b_. Factories are create_<animator_id>(bank_id: int) -> result 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. 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.
Asset batch identity and explicit rebind
Animation documents and metadata MUST participate in the shared asset batch revision, affected-reference analysis and publication exclusion. An identical PNG reimport preserves artifact identities, ordering, hashes and animation bindings. Append allocates only new artifact identities without renumbering existing frames. Removal, incompatible replacement or size/order/layout change MUST enumerate affected animation/scene/metadata references and require explicit mapping in the same batch.
Existing prepare/apply rebind validation remains authoritative. A batch does not silently retarget frames by path or list position, relax validation, or publish the bank before its declared binding changes. Revalidate both document and bank revisions at commit and recover the whole declared batch before any shared animation reader observes it. Record stale generated dependents explicitly; an ownership edge does not execute a generator or promise recomposition.