RUNE-1003: Story Morph Replacement Proposed
Summary
morph preserves visual continuity while replacing an existing named sprite instance with a new sprite implementation under the same name. It is not a shared-sprite bridge between two separate identities; that is transition.
Form
- create@hero:
./sprites/title-card:
title: "Q1 Results"
- morph@hero:
./sprites/chart-panel:
title: "Revenue by region"
sizing: auto
with: $smooth
- wait: $heromorph@name requires the sprite name to already exist. A duplicate create@name is a validation error; replacement is explicit through morph@name.
The first payload key is the replacement Sprite Type ID. Its value is the Sprite Primary, and remaining payload siblings are Sprite Field Initializers. Common targets such as x, y, and opacity initialize the replacement; sizing and with are morph Action Fields.
When target public sprite properties are omitted, morph inherits descriptor-backed common properties from the current public sprite only for channels that the replacement did not set. Replacement target values are not overwritten by old model values; the old sprite supplies presentation start values for compatible animation.
Identity Timing
After successful installation, the public sprite name resolves to the new implementation. Later actions that target name write to the new implementation, even while the visual transition is still running. A failed morph restores the original public identity.
The old implementation becomes an internal transition source only. It may be captured as a visual snapshot or retained behind a runtime proxy, but it is not a second public sprite identity.
Each implementation has a StorySpriteIdentity. Successful morph MUST transfer the original logical identity to the replacement and terminate the replacement's temporary identity. Stored layout snapshots therefore follow a compatible replacement. Destroy terminates the logical identity; destroy followed by same-name create MUST NOT inherit it.
Composition Space
Morph MUST preserve the original root composition space. It captures whether the target belongs to world or screen, installs the replacement in that same space, and transfers identity without changing membership. Morph cannot move a Sprite across spaces; changing space requires destroy and create.
Execution Steps
- Validate that the sprite exists and instantiate the replacement.
- Reject incompatible replacement kinds and inherit omitted targets before scene mutation.
- Capture the original root space and rename the old public sprite to an internal deletion name such as
__DEL_hero. - Bind the replacement to the public name in the captured space.
- Transfer logical identity, match compatible properties, seed presentation starts, and apply target assignments.
- Cross-fade render-backed whole-element opacity when
withis provided. - Delete the internal old Sprite after completion, or immediately without
with.
Steps 3-7 are transactional for scene topology. If installation or assignment fails, morph removes the replacement when present, transfers logical identity back when needed, and restores the original public name, opacity, and space. This prevents orphan __DEL_ identities. If rollback also fails, both errors are reported.
Sizing
morph.sizing is backed by StorySizing and uses the same sizing strategies as shared-sprite transition:
sizing | Meaning | Best for |
|---|---|---|
auto | sprite preference or fallback to resize | default authoring |
resize | interpolate real x/y/w/h and redraw at each sampled size | vector shapes, rounded rects, bars, panels |
scale | scale a visual snapshot to the target rect | images, thumbnails, video clips, complex snapshots |
clip | keep target at real size and reveal with clipping | text-heavy panels, drawers, detail views |
none | interpolate position and cross-fade only | labels, callouts, weak visual links |
Default sizing is auto. Without sprite metadata, auto falls back to resize.
v1 Interpolation Scope
v1 morph interpolates whole-sprite geometry, opacity, sizing, and compatible descriptor properties. LayerSprite additionally maps compatible same-name children recursively. Arbitrary cross-type deep mapping, path topology morphing, and mesh morphing remain future work.
Rationale
Story scripts often have a single "current hero" that changes from title card to chart to summary. Same-name morph preserves that authoring identity without forcing extra intermediate names, while the separate transition action keeps two-identity shared-sprite bridges explicit. Identity transfer also keeps layout snapshots attached while immutable space prevents composition corruption.