Files
prometeu-studio/docs/specs/studio/12. Animation Authoring Specification.md
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
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.
2026-11-11 01:21:25 +00:00

160 lines
9.2 KiB
Markdown

# 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.
## 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.