Frame ordering and rendering invariant

Frame ordering is a serialization invariant: children of a frame must appear before the frame element itself. Maintainers need this rule when creating, transforming, or testing scene element arrays because incorrect ordering can produce incorrect rendering and clipping.

Required order

For each frame, serialize its children contiguously before the frame:

[
  other_element,
  frame1_child1,
  frame1_child2,
  frame1,
  other_element,
  frame2_child1,
  frame2_child2,
  frame2,
  other_element
]

The rule applies independently to each frame. Other elements can appear before, between, or after frame groups when their own relationships permit it.

The important relationship is the direction of serialized order, not the visual stacking order a user may expect from a canvas editor.

Why the invariant matters

When the order is wrong, the editor can still function, but elements may not render or clip correctly. The renderer also relies on the ordering for performance optimizations. A passing type check does not prove that a transformed scene preserves this runtime invariant.

Frames are container-like elements. Treat the frame and its children as one ordered group when a transformation inserts, duplicates, or reorders elements.

Reference behavior

The frame tests exercise adding elements to frames, dragging elements into a frame, resizing a frame over an element, and duplicating selected elements. They assert element-type order with an assertOrder helper. Use these tests as the regression boundary when changing frame operations.

A useful assertion has the shape:

expect(elements.map((element) => element.type)).toEqual(expectedOrder);

Adapt expected types and identifiers to the scenario under test; do not rely on a visual screenshot to prove serialized order.

Failure diagnosis

If a frame child disappears or is clipped incorrectly after a scene transformation, inspect the serialized array first. Confirm that every child precedes its frame and that the group was not split by an insertion. Then reproduce the operation covered by the frame tests and add an assertion for the failing order.

Next steps

Use Use frames, bindings, images, and web embeds for reader-facing workflows, then consult Element data and creation reference when generating scene elements.