Crate cvkg_layout 

CVKG Agentic Development Guidelines (v1.2)

All AI agents contributing to this crate MUST follow ALL seven rules:

── Karpathy Guidelines (1–4) ────────────────────────────────────────────

1. THINK FIRST – State assumptions. Surface ambiguity. Push back on complexity.
2. STAY SIMPLE – Minimum code. No speculative features. No unasked-for abstractions.
3. BE SURGICAL – Touch only what’s required. Own your orphans. Don’t improve neighbors.
4. VERIFY GOALS – Turn tasks into checkable criteria. Loop until they pass. Never commit broken.

── CVKG Extended Protocols (5–7) ──────────────────────────────────────── 5. TRIPLE-PASS – Read the target, its surrounding context, and its full call graph 6. COMMENT ALL – Every major pub fn, unsafe block, and non-trivial algorithm in 7. MONITOR LOOPS – Check every tool call / command for progress every 30 seconds.

Sources:

Structs

AnimationEngine

Manages active physics transitions for layout bounding boxes.

AspectRatio

Constrains a child to a specific aspect ratio.

EdgeInsets

Edge insets for padding, margins, and safe areas

Flex

Flex - a container that distributes space among its children flexibly

FocusCandidate

A focusable element produced by compute_focus_order.

Grid

A layout engine that computes coordinates for children positioned in a 2D grid.

HStack

HStack - lays out children horizontally

LayoutCapabilities

LayoutSpatialEntry

A node entry stored in the spatial index after layout completes.

LayoutSpatialIndex

Axis-aligned 2-D quadtree that indexes laid-out view bounding boxes.

Padding

A layout view that adds padding around its child.

ProgressiveLayoutContext

Opt-in wrapper that breaks a single synchronous layout pass into incremental batches so the UI thread is not blocked for large child lists.

SafeArea

A layout view that respects safe area insets (notches, status bars).

SafeAreaEdges

Spacer

Spacer - a layout view that expands to fill available space

TaffyLayoutEngine

The central Taffy engine that computes flexbox and grid layouts. Stored opaquely inside cvkg_core::LayoutCache::engine.

VStack

VStack - lays out children vertically

ZStack

ZStack - lays out children on top of each other

Enums

GridTrack

Track sizing strategy for a single grid track (row or column).

LayoutModality

The current input modality that the layout engine adapts to.

Functions

compute_focus_order

Compute a deterministic keyboard-focus traversal order for a flat list of FocusCandidates.

layout_capabilities

Returns the layout capabilities supported by this engine.

size_views_parallel

Compute size-that-fits for a batch of independent subviews in parallel when the parallel cargo feature is active. Falls back to sequential iteration when the feature is absent or when rayon would not help (≤ 1 view).

validate_reading_order

Validate that the focus order computed by compute_focus_order is consistent with visual reading order (P1-69 contract).