16.1.1 World Coordinates🔗ℹ

A scene uses mathematical coordinates. Positive x points right. Positive y points up. A camera converts these world coordinates to pixels, where positive y points down.

Lengths in ordinary Visual values are normally measured in world units. Camera width and height are measured in pixels. Rotation is measured in counter-clockwise radians.

SCENE-X also has frame space. A frame-space Visual uses an origin-centered mathematical coordinate system attached to the output frame. Positive x still points right and positive y still points up. Its visible width is captured when the frame-space wrapper is constructed, so later world-camera pan and zoom do not move or resize the overlay. The current output pixel width and height are still used when rendering, allowing the same semantic frame coordinates to scale with output resolution.

16.1.2 Visuals and Identity🔗ℹ

A Visual is semantic model data. It is not a Pict. Every Visual has a stable symbol identity and a reference position. A Visual may also implement the affine-Visual protocol for rotation and scaling and the opacity-Visual protocol for global opacity. A group is a Visual whose ordered children are other affine Visuals.

Identity is explicit:

(circle #:id 'moving-circle)

Two top-level Visuals with the same identity cannot be present in one scene state. Immutable updates must preserve identity. A group’s direct children must have distinct identities and no descendant may reuse that group’s identity. The same local child identity may occur in separate branches, since complete nested paths remain distinct. A custom affine Visual is treated as one leaf.

Built-in group and formula children are addressable with a nonempty nested Visual path such as '(equation numerator) or '(A row-1 col-2). Formula-part names form a local namespace inside one formula assembly; a formula-part transformation still targets the containing top-level assembly and updates its parts collectively.

16.1.3 Text and Formulas🔗ℹ

A plain-text Visual stores one line of Unicode text together with font, color, alignment, transform, and opacity data. The string is copied into immutable model storage. Plain-text model values do not contain a Pict, font% object, drawing context, or platform font handle.

A formula Visual stores a LaTeX mathematical snippet together with its display mode, semantic font size, preamble, ordered typesetting options, alignment, transform, and opacity. Formula source and option strings are also copied into immutable model storage. A formula model value does not contain a Pict, PDF page, Poppler value, cached TeX result, or running process.

Font and formula sizes are measured in local world units. Horizontal and vertical alignment select the point of the untransformed text or formula box that lies at the Visual’s reference position. Alignment is resolved first; scale and rotation are then applied around that anchor. Both kinds of Visual can be top-level scene values or ordinary affine children of a group.

Plain text supports one line only. Carriage returns and newline characters are rejected. Formula source may contain line breaks because they can be meaningful to LaTeX. An empty plain-text or formula string is valid and produces stable transparent local geometry.

Formula rendering is a separate adapter effect. A nonempty formula requires latex-pict, LaTeX, and Poppler when it is converted to a Pict.

A formula assembly stores explicitly named formula parts in back-to-front order. An ordinary assembly uses independently typeset formula Visuals at caller-selected local positions. A tagged formula instead typesets all author-declared fragments in one TeX document and records each fragment as an SVG group at its TeX-determined local position. A formula correspondence records an explicit one-to-one list of source and destination-part names. The transform-formula-parts request compiles it against the current source assembly and produces deterministic moving and fading layers.

16.1.4 Paths🔗ℹ

A path is local semantic geometry. It contains ordered subpaths, and each subpath contains a start point followed by ordered line or cubic Bézier segments. Subpaths may be open or closed. A line segment stores its endpoint. A cubic segment stores two control points and its endpoint; its start is the previous point in the subpath.

Traversal order is also reveal order. Path length is measured in local world units. A closed subpath includes its implicit straight edge back to its start. Line length is computed directly from its endpoints. Cubic length is a deterministic approximation. Partial geometry selects an interval of the total ordered arc length and preserves cubic segments as cubic segments.

Path geometry does not contain world translation, Pict values, drawing contexts, or pixels. A path Visual combines local path geometry with an affine transform and style. morph-to interpolates paths that already have corresponding structure. morph-to-normalized first applies the limited cubic normalization described by path-geometry-normalize-for-morph. morph-to-aligned additionally selects closed-loop phase/direction before that normalization. morph-to-open-aligned selects the endpoint direction for one open source/destination pair before normalization. morph-to-open-compound-aligned globally pairs equal-count open subpaths and selects endpoint direction independently within each pair. morph-to-mixed-compound-aligned partitions compound correspondence by open/closed topology, globally pairs within each class, and then restores source subpath order before normalization. morph-to-topology-changing extends that correspondence with deterministic births/deaths when topology-class subpath counts differ. SCENE-AI keeps bounds-center seeds as the default and also permits explicit shared local birth/death anchor points. SCENE-AJ optionally assigns finite birth/death costs so a poor real correspondence may be replaced by local collapse and regrowth even when topology counts match. SCENE-AK adds sparse per-subpath birth/death anchor overrides keyed by original endpoint subpath indexes. SCENE-AL adds sparse per-subpath numeric birth/death cost overrides using those same original endpoint indexes. SCENE-AM adds sparse additive real-match penalties keyed by original source/destination index pairs. morph-to-compound-aligned first globally pairs equal-count closed subpaths and applies the same loop alignment within every pair. create and uncreate animate semantic partial paths. None of these operations animate a finished Pict.

transform-shape is the higher-level replacement operation for ordinary diagram shapes. It changes a present top-level Visual into a fresh destination Visual. Atomic built-in paths, circles, and rectangles use automatic outline correspondence; groups and other endpoint types use an intentional cross-fade fallback rather than claiming a contour correspondence they do not have.

transform-matching-visuals extends that operation over the leaves of ordinary group trees. It first honors explicit relative paths, then searches stable leaf paths and conservative built-in shape correspondence. Formula and glyph transitions retain their more specialized tagged-TeX matching API.

16.1.5 Arrows and Cartesian Axes🔗ℹ

An arrow Visual stores one ordered shaft from a start point to an end point. The untransformed midpoint is its reference position. Optional triangular tips can be attached independently to the start and end. Tip dimensions are local world-unit geometry. Stroke width is cosmetic output style.

An axis range stores a minimum, maximum, and regular positive tick step. The range must contain zero because the built-in Cartesian axes cross at numeric coordinate (0, 0). Tick values are ordered nonzero multiples of the step that lie in the closed range.

An axes Visual maps the complete numeric x and y ranges to explicit local x and y lengths. It contains two shafts, regular ticks, and optional tips at the maximum x and y endpoints. Numeric coordinates can be converted to points in the axes’ containing coordinate system and converted back again. The conversion includes the axes’ translation, rotation, and positive scale.

Arrows and axes are pure semantic values. Their model modules do not contain Picts, drawing paths, drawing contexts, pixels, or text labels. The built-in adapter derives ordinary path geometry when rendering them.

16.1.6 Sampled Function Graphs🔗ℹ

A sampled function graph is ordinary semantic path geometry produced from a one-variable numeric procedure and an axes Visual. Sampling happens once when sample-function-path or function-graph is called. The returned value does not retain the procedure.

Finite real results become ordered samples. #f, positive infinity, negative infinity, and NaN create explicit breaks. An optional maximum y jump can reject a connection between two finite samples. Accepted segments are clipped to the displayed axes rectangle by default.

Function graphs use explicit 'linear or 'smooth interpolation. Linear remains the default. Smooth interpolation converts every accepted run to semantic cubic Bézier segments derived from uniform Catmull-Rom tangents. Clipping happens before interpolation, and smooth controls are clamped to the axes rectangle when clipping is enabled.

A graph Visual copies the axes translation, rotation, and scale at construction time. It is an ordinary path Visual and therefore uses the existing path renderer, opacity protocol, group composition, create, uncreate, and affine animation requests.

16.1.7 Parametric Curves and Data Plots🔗ℹ

A parameter range stores an ordered start and end value. The values may increase or decrease. Parametric sampling includes both endpoints and calls a one-argument procedure in that order. Each call returns one vec2 or #f. A coordinate becomes one sample; #f creates a gap.

An ordered data series is a proper list of vec2 values and #f gaps. List order is traversal order. The library does not sort the points by x, infer time order, or remove repeated coordinates.

Parametric and data plots can reject adjacent samples farther apart than an explicit Euclidean distance in numeric-coordinate units. They share the same segment clipping, run construction, and linear or smooth interpolation rules as function graphs. Empty input, one isolated point, or an isolated finite sample creates no drawn segment.

parametric-curve and data-plot return ordinary path Visuals whose transforms are construction-time snapshots of their axes. The sampling procedure and input point list are not stored.

16.1.8 Point Markers, Scatter Plots, and Filled Areas🔗ℹ

A point-marker Visual stores one closed marker shape, local size, fill, stroke, affine transform, and opacity. A scatter plot is an ordered semantic group of such markers placed from numeric coordinates in an axes snapshot. Marker identities are deterministic and include the original input index. Gaps and clipped points are omitted without renumbering later markers.

A filled coordinate area is ordinary closed path geometry derived from accepted function-graph or ordered-data runs. Each visible run is closed to one horizontal numeric baseline. Discontinuous runs remain separate. Smooth interpolation keeps cubic graph segments rather than flattening them. Area Visuals store only geometry, style, transform, and opacity; they do not retain the sampling procedure or source list.

16.1.9 Scene States and Scenes🔗ℹ

A scene state is one complete snapshot of the top-level Visuals in a scene. It stores both an identity lookup table and a significant drawing order. Drawing order is back to front: later Visuals are painted over earlier Visuals. A group occupies one top-level entry; its children keep a separate back-to-front order inside the group.

A scene is an immutable timeline. A scene contains chronological play and wait clips. Each play clip stores its complete starting state and compiled animation endpoints. Sampling one frame does not depend on sampling any earlier frame.

16.1.10 Transforms🔗ℹ

The established affine-transform value stores translation, rotation, and scale. Components are applied in this fixed order:

scale, then rotate, then translate

Scale is stored as positive x and y factors. SCENE-CY-A adds separate linear2 and affine2 values for a full matrix and translation. apply-affine and apply-matrix map a world Visual through those values. SCENE-DK extends the map layer to ordinary nested paths: a named child can be mapped inside an already-mapped group without flattening the group. The existing decomposed affine-Visual protocol remains available for Visual implementations; the general-map wrapper supplies the bridge through a nested group tree.

A group may be translated and rotated normally, but its own legacy scale must be uniform. A uniform parent scale and rotation compose exactly with each child’s existing decomposed transform. Allowing a non-uniform parent scale followed by a rotated child can create shear, which the legacy transform model cannot represent. Use apply-affine on the complete top-level group when that is the intended mathematical operation.

16.1.11 Groups🔗ℹ

A group is a semantic composite Visual. Its child list is stored in significant back-to-front order. Child positions are local to the group anchor. A child can itself be a group, so transforms can be nested.

During rendering, the group rotation and uniform scale are inherited by each child. The group translation places the complete composite in its parent coordinate system. Child opacity is applied to each child, and group opacity is applied to the complete composed result. Thus, opacity values multiply through nested groups.

Groups contain model values only. They do not contain Picts or renderer callbacks. The Pict adapter composes their children recursively and passes the same explicit renderer list to every descendant.

16.1.12 Relative Layout🔗ℹ

Relative layout is an adapter-level calculation. It renders a Visual with an explicit camera and renderer list, converts the resulting Pict dimensions back to world units, and returns immutable position updates. It is not stored in a scene, group, formula assembly, or Visual model value.

A layout box is the complete symmetric Pict box around a Visual’s reference position. It includes transparent padding and anchor padding; it is not a tight outline of visible ink. Layout must use the same camera and renderer list as the final rendering when exact spacing matters.

16.1.13 Opacity🔗ℹ

Global opacity is semantic model data in the closed interval from zero through one. Zero means completely transparent. One means fully opaque. Intermediate values multiply the complete rendered Visual, including fill and stroke.

Opacity is applied after Pict renderer selection. It does not change a Visual’s geometry, identity, drawing order, Pict bounds, or reference position. A zero-opacity Visual remains in the scene state until an operation removes it.

16.1.14 Time and Frames🔗ℹ

Scene time is measured in seconds. Exact rational times work and are useful in tests. For a scene duration D and frame rate fps, the frame count is:

ceiling(D * fps)

Frame n samples the scene at exact time n/fps. The exact scene endpoint is not normally a frame sample. Add a wait clip when the final state must remain visible.

16.3.1 Robust Pointwise Maps🔗ℹ

SCENE-DQ extends SCENE-CY-C’s nonlinear companion to the affine-map layer. It acts on world-space points and samples a path before mapping it, so a line under a nonlinear map becomes a visible curve rather than a chord joining two transformed endpoints. The exact caller Visual is retained at clip time zero. Adaptive refinement checks the deviation of a mapped midpoint from its mapped chord, while a failed map sample can split the result into separate subpaths.

Path Visuals, circles, rectangles, axes, and arrows are converted to sampled path geometry. Groups retain their ordinary hierarchy and names. A nested target is resolved into world coordinates and rebased through its invertible enclosing affine map, preserving its siblings and their paths. Text, images, and other affine leaves without an exposed path remain at their original resolved world placement so they stay legible; they are not secretly raster-warped. The request rejects derived Visuals and frame-space overlays. It conflicts with simultaneous same-target spatial, style, opacity, formula, or path changes, because it replaces the complete sampled Visual tree.

#:samples gives the initial positive number of pieces per original line or cubic segment. With the default #:adaptive? #t, intervals whose mapped midpoint differs from their mapped chord by more than #:tolerance are bisected, up to #:max-depth. At 'split discontinuity policy, a raised error or an invalid map result omits that interval and leaves adjacent valid fragments disconnected; 'error propagates it. Point maps should be pure because refinement may call them more than once at a source point.

The exact source Visual is retained at clip time zero; authors normally supply (homotopy p 0) equal to p. The map must be pure, may be called repeatedly at a source point by adaptive refinement, and must return a finite vec2? for every retained sample. Nested targets, supported geometric leaves, adaptive sampling, and 'split versus 'error discontinuity semantics are the same as for apply-pointwise. As a sampled approximation, phase-dependent adaptive refinement can choose different path subdivisions at different phases; this API does not infer continuous topology changes over the full time interval.

When target is a Visual value it must implement both gen:visual and gen:stroke-width-visual. When it is a symbol, scene-play checks the resolved Visual while compiling the request. Compilation validates the getter value, calls visual-with-stroke-width with the requested endpoint, requires the result to remain a stroke-width Visual with the same identity, and checks that the endpoint was installed exactly.

Stroke width is its own animation component. It may run simultaneously with translation, rotation, scale, opacity, or path-geometry changes for the same identity. Two overlapping same-target stroke-width requests conflict after AN–AR schedule expansion; touching requests may chain through a succession or other nonoverlapping schedule.

The numeric interpolation follows the leaf easing like movement and ordinary opacity animation. With an easing whose endpoint is one, the exact requested numeric width is installed at the leaf endpoint even when the starting width or schedule arithmetic is inexact. For custom Visuals, compilation also rejects a setter that changes the exact/inexact representation of that requested endpoint.

The semantic width domain is renderer-independent. The default Pict/racket/draw backend accepts cosmetic pen widths from 0 through 255 pixels and reports a renderer error for larger values. Within that backend, width zero is a device-dependent hairline rather than an instruction to remove the stroke.

Compatible solid colours, linear gradients, radial gradients, and checker patterns interpolate through paint-lerp. At exact progress zero and one, the exact source and destination paint objects are installed. Different paint kinds (or gradients with unequal stop counts) are rejected during scene compilation; use an explicit cross-fade of two Visuals for that change.

Fill color owns the 'fill-color animation component. It may overlap same-target movement, rotation, scaling, opacity, stroke width, stroke color, and path geometry. Overlapping same-target fill-color leaves conflict after schedule expansion; touching leaves are legal.

When target is a Visual value, it must implement both gen:visual and gen:opacity-visual. When it is a symbol, scene-play checks the current Visual with that identity while compiling the request. A missing target or a Visual without valid semantic opacity raises an exception.

The request changes only the opacity component. It preserves identity, position, affine transform, geometry, style, drawing order, and group child order. It may run at the same time as movement, rotation, scaling, or path morphing for the same identity. It conflicts with another same-target request that changes opacity, including fade-in and fade-out.

fade-to does not add or remove the target. Its endpoint follows the easing result, like movement and morphing. An unusual easing procedure that returns zero at the end therefore leaves the starting opacity in place.

The Visual’s identity must be absent from the scene before the play clip. scene-play adds a placeholder with the same identity, position, geometry, affine transform, style, and drawing position, but with opacity zero. Several fade-in requests add their placeholders in request order, in front of Visuals already present. When the supplied Visual is a group, the complete child tree is introduced as one top-level Visual.

All requests in the play clip compile against the prepared shared start state. Movement, rotation, scaling, and path morphing can therefore target a Visual introduced by fade-in, even when those requests appear before the fade-in request. These operations change different components.

At interior samples, opacity is interpolated from zero to the opacity stored in visual. At the structural endpoint, the supplied opacity is installed regardless of the easing result. This guarantees that the complete Visual is present after the clip. An unusual easing procedure can therefore cause a jump at the exact clip boundary. A Visual whose supplied opacity is zero is introduced structurally but remains invisible.

A fade-in changes both opacity and scene presence. It conflicts with another same-target opacity request and with another same-target introduction or removal request. In particular, fade-in cannot be combined with same-target create, uncreate, or fade-out.

When target is a symbol, scene-play checks that the current Visual implements the opacity protocol and returns a valid opacity. A missing target or a Visual without semantic opacity raises an exception.

Movement, rotation, scaling, and path morphing may run at the same time for the same identity. The Visual remains present at interior samples, so those components continue to update while it fades. At the structural endpoint, the Visual is removed regardless of the easing result. A group and its complete child tree are removed as one top-level Visual. An unusual easing procedure can therefore leave it visibly opaque just before the boundary and absent at the boundary.

A fade-out changes both opacity and scene presence. It conflicts with another same-target opacity request and with another same-target introduction or removal request. In particular, it cannot be combined with same-target fade-in, create, uncreate, or fade-to.

The target must be present when scene-play compiles the request. When target is a symbol, the built-in path-Visual requirement is checked at that time. The target’s current path at the beginning of the clip must be compatible with destination according to path-geometry-morph-compatible?. Incompatible structure raises an exception before the clip is added.

At each sample, morph-to uses path-geometry-lerp with the clip’s eased progress. It interpolates subpath starts, line endpoints, cubic control points, and cubic endpoints. It preserves the target’s identity, affine transform, opacity, fill, stroke, stroke width, and drawing position. It does not copy style or placement from another Visual.

A morph can run at the same time as movement, rotation, scaling, or opacity fading for the same identity because those requests change different components. This includes morphing a Visual introduced by fade-in or removed by fade-out. A second strict, normalized, or aligned morph, create, or uncreate for the same identity conflicts because all of them change the path-geometry component.

Like translation, rotation, and scale, morphing follows the easing result at the clip endpoint. It has no special structural completion rule. An unusual easing function that does not map one to one can therefore leave the final path between the source and destination, or at the source.

When scene-play compiles the request, it reads the target’s current path and normalizes that path together with destination. Compilation requires the pair to satisfy path-geometry-morph-normalizable?. A subpath-count, closure, or point-only/nonempty mismatch raises an exception before the clip is added.

At eased progress zero, the exact original source path is used. At eased progress one, the exact requested destination is used. At interior progress values, the normalized cubic source and destination are interpolated with path-geometry-lerp. This preserves the visible source and destination figures while allowing stored line-versus-cubic and segment-count differences supported by the normalizer.

The operation preserves Visual identity, reference position, rotation, scale, opacity, fill, stroke, stroke width, and drawing order. Movement, rotation, scaling, and opacity fading may run simultaneously for the same identity. A strict morph, another normalized or aligned morph, create, or uncreate conflicts because all of them change path geometry.

Like morph-to, this request follows the easing result and has no structural endpoint override. An easing function that returns zero at the clip endpoint therefore leaves the exact source path. An easing function that returns one produces the exact requested destination.

This request does not reverse a path, rotate a closed path’s starting point, reorder subpaths, add or remove subpaths, change closure, or invent drawn segments for a point-only subpath.

The target must be a present built-in path Visual when scene-play compiles the request. Both source and destination must each contain exactly one positive finite closed subpath. allow-reverse? and sample-count have the same meaning as for path-geometry-align-for-morph.

At interior eased progress values, interpolation uses the automatically aligned and normalized destination. At eased progress zero, the exact original source path is used. At eased progress one, the exact requested destination object is used, not the phase-shifted or reversed internal working representation. The endpoint therefore preserves caller-requested semantic storage while the visible closed loop has the correspondence selected for the interior morph.

The request changes the path-geometry component. It may run simultaneously with movement, rotation, scaling, or opacity changes, and conflicts with strict, normalized, or another aligned morph plus create and uncreate on the same target. Like the other morph requests, it follows the easing result and has no structural endpoint override.

The target must be a present built-in path Visual when scene-play compiles the request. Source and destination must each contain exactly one positive finite open subpath. allow-reverse? and sample-count have the same meanings as for path-geometry-align-open-for-morph.

Interior eased progress uses the selected endpoint direction and normalized geometry. Eased progress zero uses the exact clip-start source path. Eased progress one installs the exact caller-requested destination object, including its original stored direction. Direction selection is therefore an interior correspondence choice rather than an endpoint rewrite.

The request changes the ordinary path-geometry component. It may compose with movement, rotation, scaling, or opacity animation, and conflicts with strict, normalized, closed-loop aligned, compound-aligned, another open-aligned morph, create, or uncreate on the same target.

The target must be a present built-in path Visual when scene-play compiles the request. Source and destination must contain the same nonzero number of positive finite open subpaths. allow-reverse? and sample-count have the same meanings as for path-geometry-align-open-compound-for-morph.

Interior eased progress uses global subpath pairing, per-pair endpoint direction, and normalized geometry. Eased progress zero uses the exact clip-start source path. Eased progress one installs the exact caller-requested destination object, including its original subpath order and stored traversal directions. Pairing and reversal are therefore interior correspondence choices rather than endpoint rewrites.

The request changes the ordinary path-geometry component. It may compose with movement, rotation, scaling, or opacity animation, and conflicts with strict, normalized, one-loop aligned, closed-compound aligned, another open-compound aligned morph, create, or uncreate on the same target.

The target must be a present built-in path Visual when scene-play compiles the request. Source and destination must be nonempty positive-finite compound paths with matching counts of open subpaths and matching counts of closed subpaths. allow-reverse? and sample-count have the same meaning as for path-geometry-align-mixed-compound-for-morph.

Interior eased progress uses topology-class global pairing, per-open endpoint direction, per-closed phase/direction, and normalized geometry. Eased progress zero uses the exact clip-start source. Eased progress one installs the exact caller-requested destination object, including its original interleaving, subpath order, and stored traversal representations.

The request changes the ordinary path-geometry component. It may compose with movement, rotation, scaling, or opacity animation, and conflicts with strict, normalized, one-loop aligned, open-compound aligned, closed-compound aligned, another mixed-compound aligned morph, create, or uncreate on the same target.

Matched real open/closed subpaths use the same correspondence rules as SCENE-AG. Unmatched destination subpaths grow from deterministic degenerate bounds-center seeds by default, while unmatched source subpaths collapse to their own bounds-center seeds. birth-anchor and death-anchor may instead be explicit finite local vec2 values shared by all unmatched subpaths on the corresponding side. SCENE-AK’s birth-anchor-map and death-anchor-map may sparsely override those shared values by original destination/source subpath index. Missing keys inherit the shared anchor and an explicit 'bounds-center entry opts that subpath back into its own center. The request snapshots both hashes immutably; index range is checked against the actual clip-start source and caller destination when the request is compiled. By default birth-penalty and death-penalty are both 'forced, preserving SCENE-AH/AI matching. Supplying both as finite nonnegative real costs enables SCENE-AJ voluntary death+birth replacement when that lowers the global correspondence cost; exact cost ties prefer fewer topology changes. SCENE-AL’s birth-penalty-map and death-penalty-map may sparsely override those shared numeric costs by original destination/source subpath index. Missing keys inherit the shared cost. The request snapshots both endpoint penalty maps immutably, and nonempty endpoint maps require numeric shared penalty mode. SCENE-AM’s match-penalty-map may be used in either forced or numeric mode. Its keys are (cons source-index destination-index) pairs in original caller storage order and its finite nonnegative values add to real-edge geometric scores only. The request snapshots this map immutably as well. Pair-key range and topology validation occurs when the request is compiled against the clip-start source and stored destination. Empty source or destination geometry is legal; any real subpath that is present must have positive finite arc length.

Interior eased progress uses the prepared/normalized geometry. Eased progress zero uses the exact clip-start source path, with no synthetic birth slots present. Eased progress one installs the exact caller-requested destination, with no synthetic death slots present. Birth/death seeds, reordering, reversal, and closed-loop phase are therefore interior correspondence only.

The request changes the ordinary path-geometry component. It may compose with movement, rotation, scaling, or opacity animation and conflicts with strict, normalized, aligned, compound-aligned, another topology-changing morph, create, or uncreate on the same target.

The target must be a present built-in path Visual when scene-play compiles the request. Source and destination must have the same nonzero number of positive finite closed subpaths. allow-reverse? and sample-count have the same meaning as for path-geometry-align-compound-for-morph.

Interior eased progress uses globally paired, phase/direction-aligned, normalized geometry. Eased progress zero uses the exact clip-start source path. Eased progress one uses the exact caller-requested destination object, including its original subpath order and storage representation. Pairing is therefore an interior correspondence choice rather than an endpoint rewrite.

The request changes the ordinary path-geometry component. It may compose with movement, rotation, scaling, or opacity animation, and conflicts with strict, normalized, one-loop aligned, another compound-aligned morph, create, or uncreate on the same target.

The default 'auto first tries a geometric transition when each endpoint is one built-in path-visual?, circle-visual?, or rectangle-visual?. Circle/rectangle pairs use a canonical eight-segment perimeter: both start at their right midpoint and correspond at the cardinal and diagonal positions. This produces an evenly rounded square-to-circle interior. Pass 'perimeter to require that primitive correspondence, or 'path to use only the general stored-path policy. Other geometric pairs use automatic topology-class pairing, including closed-loop phase/direction and open-path direction; when counts differ, they try deterministic birth/death preparation. The source and destination styles are alpha layers over the same intermediate outline, so a fill/stroke change fades naturally while the geometry moves. Their transforms are interpolated too.

If either endpoint is a group, image, text, formula, SVG tree, custom Visual, or atomic geometry that cannot be prepared safely, 'auto keeps the exact endpoint trees and cross-fades them at their own positions. This is a deliberate graceful fallback: it does not flatten a group or manufacture a semantic mapping between its children. 'morph requires the geometric case and raises an exception otherwise. 'cross-fade always selects the fallback and ignores the correspondence controls.

At exact start, the source is unchanged. At interior samples it is hidden and a temporary frontmost layer is drawn. At structural completion, regardless of the easing result, the source is removed and the exact caller-supplied destination Visual is installed. Temporary path conversions and normalized outlines are therefore never retained in later clips.

The operation reserves all ordinary Visual components and presence for both source and destination identities. It cannot be combined in one play clip with another animation of either endpoint.