Reuse and morph

Mental model

Reuse in Story is about keeping authored identity clear while letting the scene change shape. A .sprite.yaml definition gives you fresh runtime instances with private internals and public fields/actions. The shipped morph action keeps one logical sprite identity while replacing its implementation.

Responsibilities and boundaries

• Composite definitions are immutable compiled authoring contracts, not shared runtime instances.
• Public Composite fields and actions are the only supported boundary across the private scope.
• morph owns replacement, logical identity transfer, and same-space continuity.

Stable current behavior

• Each create of a local Composite path materializes a fresh instance with its own private layout namespace, bindings, and timelines.
• The first declared Composite field is the construction primary, and the first field in an action declaration is that action’s invocation primary.
• Action calls get fresh immutable input frames but share the owning Composite’s persistent state and private composition.
• Successful morph transfers the original logical identity to the replacement, so later layout results and later actions follow the new implementation.
• morph uses the sizing vocabulary auto, resize, scale, clip, and none.

Current limitations

• Composite field animation is currently limited to fields declared as animatable number values.
• Composite sprites still use scale-based sizing rather than width/height/align as public surface area.
• morph rejects a source or target subtree containing a CompositeSprite. Composite instances remain reusable authoring boundaries, but Phase 1 does not recursively replace their private runtime trees.
• V1 morph interpolates whole-sprite geometry, compatible properties, and layer-recursive same-name children; it is not arbitrary deep cross-type mesh or topology morphing.
• RUNE-1004 describes a proposed shared-sprite transition contract, but the current descriptor registry and generated syntax do not expose a transition action. It is Reference design, not shipped Story behavior.

How the pieces connect

1. Compilation caches each .sprite.yaml definition once by canonical path.
2. Construction binds public fields plus inherited sprite properties into a fresh instance.
3. Parent stories talk only through public fields/actions, while the private subtree manages its own child timelines and bindings.
4. morph swaps one public implementation in place and keeps the logical identity.
5. The proposed transition Spec explores continuity between two separate identities without changing the current morph lifecycle.

Go deeper

• Learn: Composition and reuse, Design system
• Examples: Presentation demo, Examples gallery
• Reference: Story syntax
• Specs: RUNE-1010, RUNE-1003; proposed detail: RUNE-1004