Crate paint_list_api 

paint_list_api — the trait + common vocabulary every engine emits into and NetRender renders from. See genet/docs/2026-05-17_paintlist_polyglot_renderer.md (design, PM-3 resolution) and genet/docs/2026-05-20_paintlist_extraction_plan.md (the move into this neutral netrender-workspace crate).

Shape

• PaintList is the producer-facing trait engines implement. Concrete impls (GenetPaintList, NematicPaintList, ScryingPaintList, inker’s document list) live in their respective engine crates and carry richer internal state (palettes, spatial trees) behind the trait’s PaintList::commands view.
• PaintCmd is the closed-set command stream the renderer pattern- matches against. Compositor primitives push/pop composition state; Draw* primitives emit one item each. PM-3: no generic extension hole — engine-specific items either map to common ops or hand off via PaintCmd::DrawExternalTexture.
• primitives holds the engine-facing display-list vocabulary (color, euclid geometry, border/line/blend enums). This crate owns that vocabulary; it does not depend on netrender. The paint_list_render crate translates PaintCmd → netrender::Scene and is the only place the two vocabularies meet.

Lowering contract

The renderer owns PaintCmd → netrender::Scene translation. The DrawExternalTexture lowering specifically is the per-frame compositor pass (ExternalTextureComposite with scene_op_boundary), not a vello SceneOp::Image. This sidesteps tile-cache invalidation for mutating textures (WebGL canvas, embedded iframes, paint worklet output, etc.) by construction.

Re-exports

pub use items::*;

pub use primitives::*;

pub use specs::*;

Modules

items

Paint-primitive payloads: the *Item types each PaintCmd::Draw* variant carries, plus supporting types (PathData, BorderDetails, gradient payloads, GlyphInstance, etc.).

primitives

Engine-facing primitive vocabulary for the PaintList layer.

specs

Compositor-primitive payloads: clip / transform / layer / shadow specs and the filter-op enum carried on LayerSpec.

Structs

CommonPlacement

Bounds-and-flags aggregator every paint item carries. In the PaintList model the clip and transform state come from compositor primitives (PushClip/PopClip, PushTransform/PopTransform), not from per-item references — so this is lighter than the GenetDisplayList::CommonItemPlacement it descends from.

EngineId

Identifies which engine produced a PaintList. Used for diagnostics and for keying the PaintEnvelope discriminant.

FontResource

A font referenced by one or more DrawText runs. Carried in the paint output’s font side-table (PaintList::fonts) rather than inline on each TextRunItem, so a font shared across many runs ships its bytes once. The renderer interns each FontResource into its font palette and maps key → its internal font id; TextRunItem::font_instance then resolves through that map.

ImageResource

A decoded image referenced by one or more DrawImage / DrawRepeatingImage items. Like FontResource, the pixels travel in the paint output’s image side-table (PaintList::images) rather than inline on each item, so an image used by several items ships its bytes once. The renderer interns each ImageResource into its atlas and maps key → its internal image id; ImageItem::image_key then resolves through that map.

PaintEnvelope

Wire shape for transporting a PaintList across IPC, fixture files, or any boundary where the producer’s concrete PaintList impl can’t be carried by name. PM-3 doc proposed enum { Genet(GenetPaintList), Nematic(...), Scrying(...) }; implementation went with a flat struct + EngineId discriminant because none of the concrete impls carry engine-specific extra fields beyond what the trait already exposes, and the enum shape would force paint-api to depend on every engine crate.

PrimitiveFlags

Per-item presentation flags. Carried inline on every CommonPlacement aggregator.

Enums

PaintCmd

One paint operation. Push-order is paint-order. The renderer pattern- matches on this to lower into its internal Scene.

Traits

PaintList

What an engine emits — the unit of paint output for one rendered frame. Fully serializable so the same value can cross IPC, sit in a fixture file for capture/replay, or feed the renderer’s lowering.