Function projectBoxAreaFraction

Project a :type:BoundingBox through its box-to-clip matrix and return the fraction of the viewport AREA it visibly covers — the metric for selector: 'screen-area'. As with projectBoxDiagonalPx, bounds are group-local when the registry supplies projection × view × group-world, or world-space when the matrix is omitted and projection × matrixWorldInverse is used; the inscribed ellipsoid below is taken in that same frame.

Orientation-stable: the box's inscribed ellipsoid, not its corners. The screen rect of a box's 8 corners grows by up to ~1.7x between a face-on and a corner-on view of the same box at the same distance, so a rect metric walks a lod ladder up and down while the camera merely orbits. The box is therefore measured through its INSCRIBED ellipsoid (semi-axes = the box half-extents), projected exactly as a dual quadric onto the image-plane conic, and then SIZED by the ellipsoid's view-axis half-chord (see projectNearDepthEllipse): in perspective the bare ellipse outline sits near the box's middle plane while its screen coverage is set by the near face, so a thick box close to the camera would otherwise read too small. The metric is sqrt(det S) of the sized ellipse's NDC shape matrix S (the product of its semi-axes). For a flat box face-on, or under an orthographic camera, it is exactly the legacy rect product halfW × halfH (the ellipse is inscribed in the face's rect); a thick box face-on in perspective reads its near-face rect exactly on the view axis, so stored thresholds keep their meaning (a screen-filling face still reads 1.0). A tilted flat card gets no depth correction. A cube at a fixed distance has the same half-chord from every direction, so its orbit metric stays constant; an elongated box still changes size when viewed from different directions.

Clipped to the viewport. The ellipse's area is scaled, per axis, by the visible fraction of its screen-space AABB, so the metric reads the portion of the screen ACTUALLY occupied: a node whose ellipse extends far off-screen but clips only a corner reads that small visible fraction (and picks a coarse level) — which matters while panning across partition tiles. The metric tops out at exactly 1.0 (full coverage); the natural pick uses threshold <= metric, so the fills-screen partition threshold (1.0) is satisfied the moment coverage is complete. The scaling is exact for an axis-aligned ellipse (every face-on view) and an approximation for a tilted one. In NDC each axis spans 2, so the value is viewport-size independent by construction.

Degenerate (lower-dimensional) CONTENT ramps to its LINEAR span. When the ellipse's RAW (pre-clip) minor semi-axis is below DEGENERATE_RECT_HALF_EXTENT — sub-pixel thin content: a straight polyline, an edge-on plane — the area reads ~0 regardless of how much screen the content spans, which would pin it to the coarsest level forever. The metric is therefore max(area, clippedSpan × (1 − rawThin / DEGENERATE_RECT_HALF_EXTENT)), where clippedSpan is the larger clipped half-extent of the ellipse's AABB: at zero thickness it reads the full CLIPPED linear span (a full-width line = 1.0), decays CONTINUOUSLY to the area as the thickness reaches the sub-pixel floor, and is exactly the area everywhere above it. A point still reads ~0 → coarsest. The ramp is gated on the RAW thinness so a wide 2D node whose CLIPPED sliver happens to be thin honestly reads its tiny visible area.

Fully off-screen reads exactly 0, including a box entirely behind the camera: a clipped interval that is INVERTED (no viewport overlap on that axis) zeroes the metric before the degenerate ramp can see it.

When the eye plane cuts the box there is no finite near-corner depth to size the ellipse at. With the camera INSIDE the box the metric saturates to +Infinity (the finest level), like the corner-rect metrics. With the eye OUTSIDE it (a node running past the camera, its far end behind the eye, including a corner poking behind the eye while the inscribed ellipsoid stays in front) the metric is the viewport-clipped area of the screen rect of the part in front of the near plane (straddlingAreaFraction): what it really covers, not the finest level for a box that only grazes a corner of the view (#2944 review B). An ORTHOGRAPHIC projection never degenerates (w stays 1), so neither applies — a camera inside a large node reads full coverage naturally because its ellipse spans the viewport. See the v3.4 spec's normative metric rules.

Exported for unit testing.