Module native 

Native paint seam - the way a plugin draws its own pixels inside the retained scene.

A plugin that owns a drawing surface (a chart, a map, a canvas) has content the core primitives cannot describe. The seam gives it an opaque leaf: the plugin contributes an ExtractedNative from a normal extract fn, registers a NativePainter for the same extension_id, and the render backend calls that painter with its own draw target when the leaf’s turn comes in paint order.

This is the same shape as QSGRenderNode in Qt SceneGraph and GskGLShaderNode in GTK 4: an opaque leaf that the scene graph positions, orders, and clips, and whose interior only the backend and the extension understand.

Contracts

• Bounds enclose the paint. ExtractedNative::bounds must cover every pixel the painter touches. The damage diff repaints exactly that rect, so paint outside it survives as stale pixels until something else damages the region.
• revision is pixel identity. Two leaves with the same extension_id, bounds, clip_to_bounds, and revision are treated as identical pixels and contribute no damage. Call next_revision whenever the content changes, or the frame never repaints. Payload identity is deliberately not part of the comparison: producers rebuild the Arc on every dirty frame, which would mark the leaf changed every time.
• Painters take &self. One painter serves every leaf carrying its extension_id, so per-frame state goes behind interior mutability.
• extension_id names a contract, covering both the concrete payload type and the API the painter expects from the backend. A backend with no painter registered for an id skips the leaf, which is what keeps a scene portable across backends.
• Bounds with no area never repaint on their own. Damage is a rect, and an empty rect is no damage, so a leaf that declares zero width or height falls back to whole-viewport damage when its revision moves. Declare the area you paint.

Producing leaves

NativeExtract resolves the placement of one entity - paint order, scroll offset, inherited opacity, hidden subtrees - the same way the built-in extractors do, and upsert_native_leaves carries the leaves across frames under one extension id so two plugins extracting in the same frame cannot evict each other’s entities.

Structs

ExtractedNative

Render-world component describing one backend-painted leaf.

NativeExtract

The hierarchy-derived facts a plugin’s extract fn needs, computed once per frame.

NativePaintCtx

What a backend hands a NativePainter for one leaf.

NativePainters

Render-world registry mapping an extension_id to the painter that draws it.

NativePlacement

Where one entity’s leaf belongs this frame, as NativeExtract resolved it.

Traits

NativePainter

Paints one ExtractedNative leaf onto a backend draw target.

Functions

next_revision

Monotonic content stamps for ExtractedNative::revision.

upsert_native_leaves

Carries one extension’s leaves into the render world, reusing each entity’s render-world entity across frames and despawning the ones that went away.