Add retained paints and shared text selection

docs/TEXTURES.md

@@ -42,6 +42,26 @@ adjacency after a free.
 Standalone images currently use `NonFiltering` sampling. Thumbnail scaling
 and filtering remain image-widget decisions, not texture-storage decisions.
 
+## Colour convention
+
+Palette literals and decoded image bytes enter Iris as straight-alpha sRGB.
+Solid paints are converted once when registered and stored in a separate GPU
+paint table as linear `vec4<f32>`; rect and glyph primitives carry only the
+paint-table index. `Paints::set` rewrites a slot in place, so a shared theme
+can change without rebuilding widgets or primitive buffers. A rect may also
+hold a `Paint` definition and resolve it to a `PaintId` on its first draw;
+independently constructed definitions deliberately receive independent slots.
+
+Standalone images, colour glyphs, and atlas pages use
+`Rgba8UnormSrgb`, which makes sampling decode their RGB channels to linear
+light. Shaders therefore always return linear values. Both window backends
+render through an sRGB texture view in `SurfaceColorSpace::Srgb`, which
+encodes exactly once on output; the clear colour is linear too. A surface
+without an advertised RGBA/BGRA sRGB view and sRGB output space is rejected
+rather than silently displaying a different colour pipeline. The readback
+test in `iris/tests/color_space.rs` guards the solid, image, and in-place
+theme-update paths end to end.
+
 ## Verification rig
 
 `scripts/rigs/gpu-probe` requests Iris's exact feature and limit set without a