Module transform3d 

The composite-time 3D transform on a promoted layer (transform3d style).

The style’s presence promotes the subtree ([PromotionReasons::TRANSFORM3D]); this module owns what happens after: the raw wire params live in LayerTransform3d (written by the style applier, overwritten per-frame by the transition/animation drivers), and sync_transform3d_matrices derives the LayerTransform3dMatrix the render side composites the quad through. The matrix reshapes the composite quad only — the capture, layout, and every main-world system see the untransformed node — so a matrix change is composite-only dirt: it never re-captures the layer itself, only re-draws the enclosing chain (same cost model as translation/group alpha).

Space conventions: the matrix is built in physical screen px (the space of composite-quad vertices and UiGlobalTransform), x right, y down, z toward the viewer (CSS’s screen space). Wire lengths are logical px and scale by the node’s scale factor; angles arrive as radians from protocol::units::Angle. Self-perspective divides by w = 1 − z/d so positive translateZ moves toward the viewer and magnifies, with the vanishing point at the resolved origin.

Structs

LayerTransform3d

The transform3d style params on a promoted layer root, exactly as merged from the wire (base style + active interaction variants). Written by apply_style_masked under the TRANSFORM3D group; the transition and animation drivers overwrite it per-frame. Removed on demotion (see evaluate_layer_promotions) — style apply never removes it, mirroring the UiTransform never-remove rule.

LayerTransform3dMatrix

The matrix derived from LayerTransform3d + this frame’s layout, in physical screen px. Separate from the params component so per-frame rebuilds (layout moves, animation) aren’t style-state changes — the same split as LayerGroupAlpha. Consumed by render extraction (composite quad) and by the transformed-picking driver (layer::pick3d).

Functions

build_transform3d_matrix

Build the composite matrix for one layer in physical screen px. border_min/border_size are the node’s border box (NOT the outset-inflated LayerCaptureRect). Canonical order around the resolved origin o: M = T(o) · P(d) · T(t) · Rz · Ry · Rx · S · T(−o) — column vectors, rightmost applies first, i.e. scale, then rotations, then translation, then the self-perspective projection, all about the pivot.

resolve_origin

The resolved pivot as an offset from the border-box min, in physical px, plus whether an unsupported unit fell back to center (caller reports — this stays pure for tests). Percent resolves against the border box, not the outset-inflated capture rect: a blur outset must not move the pivot.

style_transform3d

Convenience for the wire params carried by a style, if any.

sync_transform3d_matrices

Derives LayerTransform3dMatrix from this frame’s layout for every promoted root carrying LayerTransform3d, and pushes composite-only dirt on change. Runs in PostUpdate after sync_layer_geometry (needs final layout) and before resolve_layer_repaints (which drains the dirt).