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
@@ -329,3 +329,10 @@ The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Sp
defines the complete type, optional-flow and storage contract.
This chapter supplies shared reachability and ownership rules; Array storage
and complete-group packing are defined by that owner.
## Animation ownership and allocation
Every AnimatorBuilder.build materializes independent private clips, frames and backing. Immutable strings retain normal sharing; assignment retains ordinary identity/aliasing. Final frame links may form private cycles and must remain rooted/reclaimable under existing GC. After construction, executed advance and sprite paths allocate no heap objects, including negative/overflow error returns.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -291,3 +291,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Executable result return groups
Emit an existing typed return group: Int32 status 0 for success or canonical nominal error case index 1..N, followed by the complete plain payload group. Unit result has only status. Error payloads use admitted typed defaults, including nullable references, without constructing payload objects. Preserve typed reference/builtin/Fn/trait groups across signatures, Registry, direct/contract calls, branches and discard. Propagation fills the enclosing inactive payload and returns immediately; handle recovers locally or remaps outward. The common backend consumes neutral typed IR with no PBS branches.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -0,0 +1,180 @@
# Core Sprite and Animation Specification
Status: Normative v1. Owner: compiler/pbs. Applies to Game stdlib major 1.
## Purpose and boundaries
The core provides ordinary executable PBS structs, not VM builtin animation types.
The caller owns bank loading, replacement and lifetime. Core validates structural
ranges and arithmetic; glyph existence and asset-to-slot correspondence belong to
the asset-aware caller. Sprite, internal clips and Animator store neither position
nor palette. Each frame is one glyph, and frame glyph IDs need not be contiguous.
The public API, private construction and executable result rules below are
normative. Finalized clips/frames are private and immutable after publication.
## Core API and ownership
```pbs
// @core:sprite exports Sprite, SpriteView, SpriteError and:
fn make_sprite(bank_id: int, glyph_id: int) -> result<SpriteError> Sprite;
// Sprite and SpriteView:
fn sprite() -> (bank_id: int, glyph_id: int);
// @core:animation exports Animator, AnimatorBuilder, AnimationError and:
declare enum PlaybackMode(Once = 0, Loop = 1);
declare enum PlaybackState(Stopped = 0, Playing = 1, Paused = 2, Finished = 3);
fn animator_builder(bank_id: int, initial_clip: str) -> result<AnimationError> AnimatorBuilder;
// AnimatorBuilder:
fn begin_clip(name: str, mode: PlaybackMode) -> result<AnimationError>;
fn add_frame(glyph_id: int, duration_ticks: long) -> result<AnimationError>;
fn end_clip() -> result<AnimationError>;
fn discard_clip() -> result<AnimationError>;
fn remove_clip(name: str) -> result<AnimationError>;
fn build() -> result<AnimationError> Animator;
// Animator implements SpriteView:
fn sprite() -> (bank_id: int, glyph_id: int);
fn state() -> PlaybackState;
fn active_clip() -> str;
fn clip_count() -> long;
fn frame_count(name: str) -> result<AnimationError> long;
fn frame_at(name: str, index: long) -> result<AnimationError> (glyph_id: int, duration_ticks: long);
fn select(name: str) -> result<AnimationError>;
fn play(name: str) -> result<AnimationError>;
fn pause() -> void;
fn resume() -> void;
fn stop() -> void;
fn restart() -> void;
fn advance(ticks: int) -> result<AnimationError>;
```
Factories are the public construction path. `[StdlibFactoryOnly]` restricts
positional/named `new` to the type's declaring module, using trusted stdlib origin.
Game code cannot forge that metadata or evade it by alias/reexport. Types remain
ordinary PBS structs. Completion/signature help must expose usable factories.
Admit the reserved attribute only on structs from trusted stdlib origin; it is
not a game-defined annotation. Use `declare contract` and `implements` in each
concrete type's module, preserving the existing PBS contract ownership rules.
Clip/frame types and backing never escape. Sprite and Animator implement
SpriteView with joint bank/glyph query, no new Sprite or effects per read.
Banks are int 0..255, glyphs int 0..65535, durations long 1..LONG_MAX,
LONG_MAX=9223372036854775807. Clip totals must not exceed LONG_MAX. Clip/frame
counts are long bounded by 4294967295; final clips/animator are nonempty. Frame
indices are zero-based longs. Tick input remains int; negative is an error,
zero has no effect and positive values are at most 2147483647.
SpriteError cases are invalid_bank, invalid_glyph. AnimationError cases, in order:
invalid_bank, invalid_name, duplicate_clip, clip_already_open, no_open_clip,
empty_clip, unfinished_clip, empty_animator, initial_clip_missing, unknown_clip,
invalid_glyph, invalid_duration, invalid_ticks, index_out_of_range, limit_exceeded,
overflow. Names are nonempty exact UTF-8 strings without implicit normalization.
Builder bank/initial name are fixed; it allows one open clip. end_clip rejects an
empty open clip without closing it; discard_clip discards only the open clip.
remove_clip requires none open. build checks open clip, empty collection, missing
initial in that order and produces Stopped at the initial clip's first frame.
Reuse must create private clips/frames for every animator. Builder edits leave
published animators unchanged. Only immutable strings may retain ordinary sharing.
No clone or external Clip attachment exists. Assignment preserves PBS identity.
Factories check bank ranges and required names before allocation; make_sprite also
checks glyph range. begin_clip requires no open clip and an unused, valid name;
add_frame requires an open clip and valid glyph/duration. For assembly operations,
check state preconditions before arguments, then names, ranges, counts and sums in
that order. Check `total > LONG_MAX - duration` before addition. Inspection checks
clip name before frame index. All recoverable failures preserve the prior draft
or animator, including failed end_clip, unknown remove/select/play and build after
removing the initial clip. Prepare candidate storage before publishing mutations.
### Executable result contract
Use the existing VM return group: first an Int32 status (0 for success, 1..N in
canonical error declaration order), followed by the complete typed plain-return
payload group. Preserve reference, builtin, function and trait-pair shapes and
nominal error identity in analysis/IR; matching slot counts do not establish type
identity. Unit result contains only status. Inactive error payload slots use
runtime-admitted typed defaults, including nullable reference defaults; they must
never be read as success values or require constructing payload objects.
`!` evaluates its operand once and immediately propagates the same error, filling
the enclosing function's inactive payload correctly even when its shape differs.
`handle` evaluates once and executes only the selected arm, preserving success,
local recovery and error remapping. Neither operation catches VM traps. Apply the
same group consistently to signatures, Registry metadata, imports/aliases, direct
and contract calls, branches and discarded results. Unit error paths must not use
the existing allocating default-holder helpers. Keep `Fn(...) -> TypeRef` grammar
and reject conversion of a result-effect function to plain Fn; successful Fn
payloads retain their ordinary typed representation.
### Playback contract
| Operation | State and cursor behavior |
| --- | --- |
| select(name) | From any state: Stopped at frame zero, zero phase, including the current name. |
| play(name) | From any state: Playing at frame zero, zero phase, including the current name. |
| pause() | Playing -> Paused; other states unchanged. Preserve cursor/phase. |
| resume() | Paused -> Playing; other states unchanged, including Finished. |
| stop() | From any state: Stopped/reset on selected clip. |
| restart() | From any state: Playing/reset on selected clip. |
| advance(ticks) | Reject negative in every state; zero is a no-op; positive advances only Playing. |
Check phase > LONG_MAX - ticks before addition; overflow leaves the animator
unchanged. Loop uses the remainder after dividing the new phase by total duration.
Once finishes only after consuming the last frame's full duration, retains its
image and clamps phase to total. Frame intervals are [start,end). Seek traverses
at most one clip's frame count, never each tick or each skipped loop. Failed
selection does not change anything; clips retain no suspended progress.
Use private finalized frame links with long duration/cumulative end, tail linking
to head, and direct selected clip/frame references. Prepare links before publishing
the animator. Advance and sprite must not allocate, including unit error returns;
array/optional wrappers must not be introduced on this path. All computations
precede visible state publication. VM resource/trap faults are not modeled domain
errors and carry no new rollback/safe-retry promise.
## External composition
The caller queries SpriteView and invokes
`Composer.emit_sprite(glyph_id, palette_id, x, y, layer, bank_id, flip_x, flip_y, priority) -> int`.
Preserve host identity `(composer, emit_sprite, 1)` and capability `composer`.
Composer does not depend on core Sprite/Animator. Palette applies only to the
current emission; query or emission does not advance playback.
Blitable and a draw manager are separate work. Entities, gameplay state machines,
events, ping-pong, clones, collision, multi-glyph frames and runtime animation
resources are outside this contract. There is no new opcode, host ABI, Registry
category or runtime metadata format.
## Authored factory and conformance
[Animation Authoring](../../studio/12.%20Animation%20Authoring%20Specification.md)
defines canonical JSON, binding drift, shared validation and generated sources.
Generated factories use the same builder and return effect as direct PBS code.
Factories construct fresh private clips; they never load banks or call the host.
Conformance must execute ordinary and optimized PBX with the production loader/VM
in dev/release, compare shared preview against native playback, and count executed
heap-allocation instructions for advance/sprite after construction, including
negative/overflow errors. Zero is mandatory. Resource/trap failures are not domain
errors and do not imply rollback or safe retry. A failure to establish zero
allocations requires an explicitly authorized decision revision.
Examples must call play on an action transition and advance for continuity;
calling play/select every frame resets playback every frame.
## Related specifications
See chapters 3/4 for source admission, 5/8 for module resolution/distribution,
9/10 for result/identity/lifetime and 13 for typed executable lowering.
## Native Composer status adaptation
The public Composer facade retains its existing int status and nine arguments.
The private LowComposer declaration uses the native Int64 status carrier and the
facade explicitly narrows it to int. This is a PBS adapter conversion using existing
intrinsics; host identity, capability, slot count and runtime behavior are unchanged.
@@ -1243,3 +1243,10 @@ may accompany them. Targets MUST be nongeneric top-level userland functions;
methods, lambdas, host/interface declarations and other declaration kinds are
invalid targets. Function names are arbitrary and do not select runtime roles.
PBS exposes no sync statement, lifecycle syscall or termination marker.
## Stdlib factory-only construction
`[StdlibFactoryOnly]` is reserved metadata on trusted stdlib structs. Both positional and named `new` are permitted only in the canonical declaring module. Imports, aliases and reexports preserve this admission boundary. Game declarations cannot forge the attribute. Public construction uses the declared recoverable factories. The existing result return-effect and `Fn(...) -> TypeRef` grammar remain unchanged.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -866,3 +866,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Factory admission and typed result identity
Factory-only admission uses trusted canonical declaration origin, never visible spelling or slot count. Reject external positional/named construction and forged metadata; omit prohibited constructors from completion/signature help and expose public factories. Result error identity is nominal through imports and aliases; a result-effect function cannot be converted to plain Fn.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -578,3 +578,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Core animation and generated module resolution
Game stdlib 1 distributes executable ordinary PBS modules `@core:sprite` and `@core:animation`. Private helpers retain definition-scoped resolution and trusted origin. Reserve `generated/animations` for project-owned virtual modules `@<project>:generated/animations/b_<uuid_without_hyphens>`; physical collisions are diagnostics. Only registered build-included banks publish factories; invalid included definitions block analysis/build.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -366,3 +366,10 @@ documents with revision-consistent text, ranges and frontend semantic context.
Hover and continued definition use that retained context. Compilation, module
admission, ABI and linking rules are unchanged. See Compiler Spec 23 §8.3 and
Studio Spec 11 for the consumer protocol and atomic write restrictions (DEC-0062).
## Executable core animation distribution
Package ordinary PBS bodies, barrels, helpers, documentation and examples for core sprite/animation in stdlib major 1. Compile these bodies through the same executable frontend path used by collections. Restrictions specific to SDK service bodies do not apply to all stdlib functions/structs. Installed consumers must not depend on a source checkout.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -420,3 +420,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Result groups and explicit animation time
A result success evaluates its payload once. Propagation and handle evaluate their operand once; only the selected recovery arm runs. Error remapping returns the enclosing error; traps are not caught. Animation advances only through explicit ticks. Queries/emissions are pure with respect to playback; repeated play/select resets the selected clip even when its name is unchanged.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -204,3 +204,5 @@ The internal resource path is `pbs-knowledge/specs/<numbered filename>.md`;
reference clients resolve IDs through the catalog instead of constructing paths.
- [Memcard Bootstrap and SDK](<26. Memcard Bootstrap and SDK Specification.md>): opt-in persistence producer and runtime-consumer boundaries.
- [Sprite and animation contract](27.%20Core%20Sprite%20and%20Animation%20Specification.md) — core API, explicit ticks, shared bank authoring and generated factories.
@@ -252,3 +252,10 @@ This specification MUST NOT:
PBS shells MUST repeat identities already published by the runtime catalogs
named in section 3.
## Animation integration contract
Executable library bodies retain frontend-owned source semantics. The common pipeline preserves ordered typed return groups, including a frontend status plus its full payload; it must not infer nominal identity from physical width or add PBS-specific branches. These groups use existing Registry/VM categories and host ABI.
See the [complete animation contract](../compiler-languages/pbs/27.%20Core%20Sprite%20and%20Animation%20Specification.md).
@@ -301,3 +301,10 @@ assigns other IDs to hooks. PBX emission consumes the existing role byte and
validates final targets, without role inference from function names or frontend
ASTs. Synthetic Init/Frame assembly is unchanged. FRAME_SYNC fixtures used to
test controlled-call rejection do not introduce frontend sync syntax.
## Animation integration contract
Executable library bodies retain frontend-owned source semantics. The common pipeline preserves ordered typed return groups, including a frontend status plus its full payload; it must not infer nominal identity from physical width or add PBS-specific branches. These groups use existing Registry/VM categories and host ABI.
See the [complete animation contract](../compiler-languages/pbs/27.%20Core%20Sprite%20and%20Animation%20Specification.md).
@@ -307,3 +307,10 @@ slots 1..64, capability memcard, unique role 3 and the boundary before launch.
This is distinct from a direct CALL to the hook. Host storage and headless transport
remain runtime-owned and absent from the common IR. See the PBS
[producer contract](<../compiler-languages/pbs/26. Memcard Bootstrap and SDK Specification.md>).
## Animation integration contract
Executable library bodies retain frontend-owned source semantics. The common pipeline preserves ordered typed return groups, including a frontend status plus its full payload; it must not infer nominal identity from physical width or add PBS-specific branches. These groups use existing Registry/VM categories and host ABI.
See the [complete animation contract](../compiler-languages/pbs/27.%20Core%20Sprite%20and%20Animation%20Specification.md).
@@ -160,3 +160,10 @@ This specification is complete enough when:
- registered asset boundaries are unambiguous;
- registry authority is explicit;
- identity survives relocation without ambiguity.
## Animation integration contract
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
@@ -250,3 +250,10 @@ This specification is complete enough when:
- the common `asset.json` shape is stable;
- raw and virtual assets share a coherent baseline contract;
- format-specific specs can build on it cleanly.
## Animation integration contract
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
@@ -307,3 +307,10 @@ This specification is complete enough when:
- runtime-facing artifact authority is explicit;
- companion artifacts are bounded;
- emitted ordering and header behavior are deterministic.
## Animation integration contract
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
@@ -631,3 +631,10 @@ per-project desktop Run is required. Explicitly disabled integration MUST remain
disabled. Preparation failure MUST remain visible in DEV readiness without blocking
project use. Opening MUST NOT publish credentials or grant/acquire agent control.
The coding client continues to own its configured stdio process and initial trust.
## Animation integration contract
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
@@ -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.
@@ -489,3 +489,10 @@ This specification is satisfied when the Studio `Assets` workspace:
- stages sensitive mutations through preview-first flows;
- proves the Studio event-driven workspace framework through lifecycle-managed local ownership;
- and behaves as a didactic helper for the packer model.
## Animation integration contract
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
@@ -192,3 +192,10 @@ shutdown through those ports. Application infrastructure owns credentials, file
locks/atomic discovery, HTTP identity checks, TOML preparation and managed
installation/runtime packaging. JavaFX consumes neutral status and actions only.
Filesystem publication MUST NOT run under a long-held authority monitor.
## Animation integration contract
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
+2
View File
@@ -100,3 +100,5 @@ terminal remains separate.
See the [specification guide](../README.md) for compiler, language and provider boundaries.
- [Sprite and animation contract](12.%20Animation%20Authoring%20Specification.md) — core API, explicit ticks, shared bank authoring and generated factories.