SouveraineOS/docs/FACE-VEIL-ASSETS.md

The veil — asset specification

What a frame of her has to be before the compositor can flash it across the whole panel at low alpha. Written 2026-08-15 against the blink curve landed in souveraine-viewtop b7ef258 and the panel facts in TASK-61.

This is a production spec for a person with an image editor open. Every number below either comes from the source or is derived from it, and each one says which.

The one-line version: cut her out on a transparent 1080×2160 canvas, export straight-alpha PNG-24, decontaminate the edges, and author her in the top third of her tonal range — because after compositing she gets about 30 code values of the panel's 255, and everything darker than that simply is not there.

---

1. Why the current frames cannot be used

Measured 2026-08-15 in ~/Projects/AniAvatar/:

file	size	PNG colour type
ani-idle.png	1024×1024	2 — truecolour, no alpha
ani-idle-blink.png	1024×1024	2 — no alpha
ani-affectionate.png	465×388	2 — no alpha
ani-alert.png	1024×1024	2 — no alpha

Twenty frames, none with an alpha channel, in two different sizes.

The black behind her is not absence, it is opaque black. Composited at the blink's 0.12 it produces a 12 % black wash over the entire panel with a faint her inside it. That reads as the screen dimming — which is exactly what expose does, and expose is a disclosure decision the gate makes. Two different mechanisms must never look the same on the glass.

So the veil needs the fourth channel, and it needs it as a real gradient: the soft fall-off at a pigtail, the edge of her jaw, the places she is barely there. A hard 1-bit cut-out will read as a sticker.

---

2. Canvas

property	value	why
Size	1080 × 2160 px	blueline's panel — scale.rs:238, BLUELINE_MODE
Aspect	1:2 (18:9)	ditto
Colour mode	RGB/8	kms.rs scans out Xrgb8888/Argb8888; 10-bit exists behind VIEWTOP_10BIT and is off
Colour profile	sRGB IEC61966-2.1	see §5
Background	transparent	no matte, no black layer, no white layer

Do not author at 540×1080 logical. The compositor renders at physical scale 2 and a logical-sized asset arrives at half resolution on a 440 dpi panel.

Her art does not have to fill the canvas. Compose her within it — the canvas is the panel, and where she sits on it is a composition decision, not a crop.

---

3. The tonal budget, which is the whole difficulty

This is the number that decides whether the art works, and it is not obvious.

The blink's peak alpha is 0.12 (atmosphere.rs, Blink::PEAK). Over the dark desktop the composited output is 0.12 × her value, so:

her pixel	what lands on the panel (of 255)
255	30
200	24
128	15
64	7
32	3
16	1
8	0 — gone

The entire image compresses into roughly 30 of 255 code values. Consequences, all of them real:

• Anything below ~8/255 in your file does not exist on the glass. Shadow detail, dark linework, the black parts of her jacket: gone.
• Work in the top third. Her useful range is about 170–255. Push midtones up; what looks blown-out in Photoshop is correct here.
• Silhouette and highlight, not portrait detail. A 1 px circuit trace at 60 % grey lands at 9/255 and is invisible. Make the tracery bright and at least 3 px at 1080 width if it is meant to read.
• Banding is a live risk. 30 levels across a gradient will step visibly, and the 10-bit path is off by default (TASK-61 Part 4). Add a small amount of noise/dither to large soft gradients — 1–2 % monochromatic — rather than relying on smooth ramps.
• This is per-frame, not per-project. If a specific moment wants to be more present, the verb can name a higher peak; the art should be authored for 0.12 and simply get stronger, never authored for 0.4 and vanish at 0.12.

The alpha channel is not subject to this budget — a pixel at alpha 1.0 in the file still only reaches 0.12 on the glass, because the blink multiplies the whole surface. Use alpha for shape, use luminance for presence.

---

4. Alpha, and the one trap that will bite

Wayland's Argb8888 is premultiplied alpha. The fork's fragment shader says so and un-premultiplies before any colour work (smithay/src/backend/renderer/gles/shaders/implicit/texture.frag).

Photoshop exports straight (unpremultiplied) alpha. That is the correct thing to export — the client that uploads the texture is responsible for premultiplying — but it means two things for you:

1. Do not pre-darken her against black to "bake in" the transparency. That is premultiplying by hand, and it will be done again downstream, squaring the alpha and producing a ghost with dark edges.

2. Decontaminate the edges. These frames were painted on black. Any semi-transparent edge pixel produced by keying that background out still carries black in its RGB, and straight-alpha compositing will show it as a dark fringe around every soft edge — worst on the hair, which is where she is softest.

   In Photoshop: Select → Select and Mask, turn on Decontaminate Colors, output to a new layer with layer mask. Or repaint the edge pixels. Check by putting her over a mid-grey layer, not over black — black hides exactly the defect you are looking for.

Export: File → Export → Export As… → PNG, Transparency on, no "smaller file (8-bit)". The result must be PNG colour type 6 (truecolour + alpha). Verify:

python3 -c "import sys;d=open(sys.argv[1],'rb').read(33);print('colour type',d[25])" frame.png

6 is correct. 2 means the alpha was flattened and the file is unusable.

---

5. Colour

The panel is the LG SW43408 — approximately DCI-P3, no EDID, 24-bit (TASK-61). viewtop scans out byte-through sRGB by default: colour management is off unless VIEWTOP_COLOR=natural|vivid is set.

So, plainly: author in sRGB, and expect the phone to render it more saturated than your monitor does, because raw sRGB code values land on P3 primaries. That is a known open defect, not a surprise, and TASK-61 Part 2 is the fix. Do not compensate for it by desaturating the source — that would make the art wrong the day colour management is switched on.

Saturated colour survives the tonal budget better than neutral colour does, which works in your favour. Her established palette is already there:

preset	primary	secondary
NeonGlow	#FF1493	#7FFF00
AuroraBorealis	#00FFFF	#7FFFD4
CherryBlossom	#FFB7C5	#FF69B4

#FF1493 and #00FFFF are also the two fringe colours a chromatic split throws (magenta leading, cyan trailing), which is why art in those two reads as belonging to this compositor rather than sitting on top of it.

---

6. Frames, naming, and how many

Keep the existing convention — ani-<posture>[-<variant>].png, lowercase, hyphenated.

Postures. FELT_STATE_ARCHITECTURE.md defines nine, and the current art does not match them:

posture (canonical)	art exists?
idle	yes
alert	yes
thinking	no
processing	yes
affectionate	yes
straining	yes
yawning	yes
listening	no
speaking	no
—	engaged exists and is not a posture

Decide before redrawing: either add thinking/listening/speaking, or retire engaged. A frame named for a state the system cannot enter will never be shown, and a posture with no frame falls back silently.

Variants per posture: -blink is required (it is the technique's name). -wink exists for affectionate and is welcome anywhere it is in character.

---

7. Memory — the constraint that caps the set size

A 1080×2160 RGBA8 texture is 8.9 MiB resident on the GPU (1080 × 2160 × 4 = 9,331,200 bytes). PNG compression does not help; that is the uploaded size.

TASK-75's measurements, on a 3.5 GB phone: QuickShell alone at 610 MB RSS, the WebKit face adding 283 MB, and a rendering storm reaching 952 MB before the kernel OOM-killed the shell.

So: twenty full-panel frames resident is 178 MB, and that is not affordable.

• Load one posture's pair at a time — base plus -blink — 17.8 MiB. Swap on posture change.
• Or author her smaller than the canvas and place her: a 1080×1200 cut-out is 4.9 MiB, and most compositions do not need the full 2160.
• Either way the client owns this budget, not the compositor. The compositor gets one surface and drives its alpha.

Say which choice was made in TASK-59 when it lands, because "why is the shell 180 MB heavier" is a question somebody will ask three weeks later.

---

8. Checklist before handing frames over

• 1080 × 2160, RGB/8, sRGB profile embedded
• Transparent background — no matte layer of any colour
• Edges decontaminated; checked over mid-grey, not over black
• Not pre-darkened against black (straight alpha, not premultiplied)
• Luminance authored in the top third; nothing meaningful below 8/255
• Fine detail ≥ 3 px and bright, or removed
• Large gradients carry 1–2 % dither
• Exported PNG colour type 6 — verified with the snippet in §4
• Named ani-<posture>[-blink|-wink].png, posture from the canonical nine
• Frame count × 8.9 MiB is a number somebody has agreed to

---

Connects to

TASK-59 (her face on the glass — owns the surface and the role), TASK-52 (atmosphere; Blink is #15 and the curve is landed), TASK-61 (why the panel renders saturated and when that stops being true), TASK-75 (the memory budget these frames spend from), FELT_STATE_ARCHITECTURE.md (the nine postures and the fourteen presets, both hers).