Screen effect rendering v1

Status: normative, part of the format-v1.0.0 contract. This document, together with effect-manifest-v1.md, is the normative rendering contract for the screen effect manifest v1. It is self-contained: a renderer for screen effects needs only these two documents. The format is tagged format-v1.0.0; until the first effect is published and the SDKs' 1.0.0 ship, every change to v1 is part of that tag (the tag is moved forward and the SDKs re-pin it).

effect-manifest-v1.md defines the manifest's shape and validation. It does not say how a renderer interprets the values. The iOS SDK, the Android SDK and the editor's web preview are three independent renderers that must agree in golden tests, so every interpretation below is pinned once, here.Each rule carries one marker:

[S] Settled by spec (§x) — already decided in the design spec (2026-09-28-ingevora-mirage-design.md); cited, not re-opened.

[P] Default — no field change — a rule on top of the existing fields.

Layer types: 1 particles · 2 full-screen sprite · 3 motion · 4 image · 5 sprite. Event sources: 1 lifecycle · 2 host. Keyframe animation: §E10.E1. CoordinatesE1.1 [S] §3.3, §4.2 — A screen effect draws in an overlay view the host places above its UI.E1.2 [P] Overlay axes: origin top-left of the overlay's bounds, +x right, +y down, in the overlay's points/dp (not device pixels). origin.x and position.x are fractions of the overlay width, origin.y and position.y of its height (0,0 top-left; 1,1 bottom-right). Rationale: the author places emitters and images relative to the screen edges.E1.3 [P] All other lengths — particle speed (per second), gravity (per second²), sizeScale, image and sprite scale, shake amplitude — are multiples of S = min(overlay width, overlay height). Rationale: one isotropic unit keeps directionDeg and spreadDeg true angles on any aspect ratio; the short side keeps sizes stable across phones.E1.4 [P] Gravity is a constant acceleration along +y (down) in overlay axes, in S/s²; negative values accelerate upward. Rationale: gravity is a world direction; the confetti scenario (speed 0.8 up, gravity 1) then rises 0.32 S and falls back, which is its intent.E1.5 [P] Rotation: degrees, positive = clockwise on screen (y-down), 0 = the asset upright as authored. Applies to rotationDeg and directionDeg. directionDeg 0 = +x (right), 90 = down, −90 = up (the confetti scenario's −90 fires upward). Rationale: consistent with the y-down overlay axes; matches CSS rotate() for the web preview.E2. Sprite sheets (types 2 and 5)E2.1 [P] Frames are laid out row-major from the top-left: columns = floor(sheetWidth / frameWidth), rows = floor(sheetHeight / frameHeight); frame k is the cell at column k mod columns, row floor(k / columns). Leftover pixels on the right/bottom edges are ignored.E2.2 [P] frameCount > columns × rows is invalid, rejected where images are decoded: at upload/publish by the API, and by the SDK's validate-before-cache (every image actually decodes). Issue code asset.sheet_too_small (decode-time, not in the manifest rules, because the manifest has no image dimensions).E2.3 [P] Frame index during playback: k = floor(tPlay × fps / 1000) where tPlay is ms since playback started. loop: true → k mod frameCount; loop: false → after frameCount − 1, the layer follows sheet.endBehavior: 1 holds on the last frame · 2 hides (visible becomes false; a later show or play sprite makes it visible again, E2.7).E2.4 [P] A sprite layer that is visible but not playing (for example one shown again after its end-hide, E2.7) shows frame 0.E2.5 [P] Sampling: bilinear, clamped to the frame's own cell (inset half a texel) so neighbouring frames never bleed in; no mipmaps.E2.6 [P] A type 2 sprite keeps its explicit fit, relative to the overlay and centred with the frame's aspect preserved: contain (1) scales it to fit inside the overlay, cover (2) scales it to cover the overlay and the overflow is cropped by the overlay. Rationale: an animation must not distort.E2.7 [P] When a non-looping sprite with endBehavior: 2 passes its last frame — visible or not (a sprite hidden by an action keeps its clock, E6.2) — its playback stops and visible becomes false. A later show makes it visible showing frame 0 without playing (E6.1 — show sets visible only; E2.4); a later play sprite replays it from frame 0 (E6.3). The end-hide is evaluated when the sprite clock advances at the start of a frame (E5.4), so a show or play sprite on the frame the sprite ends wins.E3. Placed layers (types 4 and 5)E3.1 [P] An image (type 4) and a sprite (type 5) each draw one textured quad:

centre C = (position.x × overlay width, position.y × overlay height) (E1.2);

width w = scale × S (E1.3); height h = w × image height / image width for type 4, and w × frameHeight / frameWidth for type 5;

rotated by rotationDeg about C (E1.5);

drawn with opacity (E4.3), premultiplied like every quad (E4.2).

Worked example (scenario effect/placed-layers.json): on a 390 × 845 overlay (S = 390) an image at position (0.5, 0.4), scale 0.5, 200 × 100 px has corners (97.5, 289.25), (292.5, 289.25), (292.5, 386.75), (97.5, 386.75).E3.2 [P] A type 5 sprite plays exactly like a type 2 sprite (E2.3, E2.4, E2.7): it starts at startMs if visible at the start (E7.2), play sprite restarts it from frame 0 and implies show (E6.3), and endBehavior applies when loop is false.E3.3 [P] Shake and pulse (E8.1, E8.3) move and scale types 4 and 5 like every other non-flash layer. Nothing else moves them in v1. Scenario effect/shake-pulse-placed.json pins it; its description works every corner out by hand.E4. Draw order and blendingE4.1 [P] layers[] is ordered. Array order is back to front: index 0 is drawn first (nearest the host app's UI, the back of the stack), the last layer on top.E4.2 [P] Compositing is source-over with premultiplied alpha, in sRGB-encoded space (no linear blending). PNGs are decoded as straight alpha and premultiplied once at load; every asset is treated as sRGB and embedded colour profiles / gamma chunks are ignored. Rationale: matches HTML canvas (the editor preview) and is cheap on the oldest devices (§4.4).E4.3 [P] opacity (types 4, 5) multiplies the premultiplied source. Particles (type 1) draw at 1; a full-screen sprite (type 2) draws at its animated opacity, which rests at 1 (E10.5); a flash (type 3) draws with its own alpha (E8.2).E4.4 [P] Asset colour/format: every asset is an 8-bit sRGB PNG (RGBA or RGB); 16-bit or palette PNGs are expanded to 8-bit RGBA at decode. Texture dimensions ≤ 1024 are already enforced at upload.E4.5 [P] Within a particle layer, particles draw in emission order (oldest first), each as an upright quad centred on its position, width sizeScale × S, height by the asset's aspect ratio, opacity 1 for its whole life, removed when its age reaches lifetimeMs. No per-particle rotation or fade in v1.E4.6 [P] Several effect instances at once (overlapping plays) are independent: each has its own clock, particles and cap; the later-started instance draws on top. Overlap itself is [S] §2 ("Simultaneous presses: both play, overlapping") — generalised here as a platform rule.E5. TriggersE5.1 [P] Lifecycle: effect.started fires at effect time 0, on the first frame processed after the effect starts; effect.ended at effect time durationMs (E7.3).E5.2 [P] Host events are delivered to every running effect instance; they are applied at the next rendered frame. Events arriving before an effect has started or after it has ended are dropped, never queued. Events with no matching trigger are ignored.E5.3 [P] When one event matches several triggers, triggers run in array order and actions in array order within each, all before the frame renders; later actions win (show then hide in the same frame = hidden).E5.4 [P] Order within one frame. At effect time t:

Clocks advance to t, in this order: a. Scheduled starts (E7.2): each type 2, 3 or 5 layer that was visible: true at start and has not been started by an action begins once t ≥ startMs, with its clock at startMs (not at t). A type 3 layer that is hidden at that moment does not begin, and the schedule is spent (a hidden motion does not run, E6.2, E8.4). A type 2 or type 5 layer begins whether or not it is visible (its clock is independent of visibility, E6.2). Autoplay clips (E10.3) begin the same way at their startMs, whether or not the layer is visible, unless an action has already started them. b. Sprite clocks, including the end behaviour (E2.7). Motion clocks: a motion whose elapsed time has reached its durationMs stops (E8). Clip clocks: a non-looping clip reaches its end at durationMs (E10.3). c. Particle pools: continuous emission that was active at the end of the previous frame (E6.6) emits every due t_k ≤ t, in order. Before each emission at t_k, the particles whose age at t_k has reached lifetimeMs are removed, so the cap (E6.4, E9.2) is evaluated at that instant. Then every particle whose age at t has reached lifetimeMs is removed (E4.5). Emission instants and particle ages are whole microseconds, computed in IEEE-754 double precision and rounded to the nearest integer with halves rounded up (every value here is ≥ 0; e.g. JS Math.round, Swift .rounded(), Kotlin Math.round — not round-half-even): the frame's T = round(t × 1000) (t in ms); T_0 is the T of the frame on which emission started (step 4); T_k = T_0 + round((k × 1 000 000) / ratePerSecond) (multiply, then divide); a particle's birth B is T_k for continuous emission and the frame's T for a burst or emit; t_k is due when T_k ≤ T; a particle has reached its lifetime at instant X when X − B ≥ lifetimeMs × 1000; its age in E6.8 is (T − B) / 1 000 000 seconds. Particles emitted for t_k < t spawn at the origin evaluated at t_k (E10.5), with this frame's S.

On the first frame only: the burstCount of every type 1 layer that is visible at start (E6.7), then the effect.started triggers (E5.1).

Host events, in arrival order (E5.2) — on the first frame this step is empty: host events that arrived before the first frame was processed are dropped.

Emission start (E6.6): every particle layer whose continuous-emission conditions now hold but which is not emitting starts emitting with t_0 = t, so its k = 0 particle is emitted now. (A hide stops emission and clears the pool when it is applied, E6.2; so show then hide on one frame emits nothing and draws nothing from the stream, E6.9.)

Draw from the resulting state, every layer at its values for t (E10.1); motions (E8.4) use the motions that are running and visible after step 4.

All actions of steps 2 and 3 apply to this frame's render, and later actions win across the whole sequence; E5.3 still orders the triggers matching one event. Particles emitted by an action (E6.4) or a burst are born at t; the burst of a layer that first becomes visible through show or emit happens when that action is applied, before the emit's own count (E6.7, E6.4).Example: an effect.started action hides a startMs: 0 layer. Step 1a starts it at effect time 0; step 2 then hides it. A type 3 motion stops (E6.2) and has no effect unless run again (a later show alone does not restart it, E6.1). A type 2 or type 5 sprite keeps its clock running from 0 and, when shown later, appears mid-animation (E6.2).The durationMs cut (E7.3): the first frame whose time t ≥ durationMs runs none of the steps above. It evaluates the effect.ended triggers, then the instance is torn down: that frame and every later one draw nothing, and host events delivered with them are dropped (E5.2).Rationale: one fixed order is the only way two renderers agree when a host event and a scheduled start touch the same layer on the same frame; pinning emission and expiry to event instants (t_k), not to frames, keeps particle pools identical at any frame rate.E6. ActionsE6.1 [P] show / hide are idempotent: they set visible and nothing else. show on a visible layer and hide on a hidden layer do nothing.E6.2 [P] hide on a particle layer clears its live particles and stops continuous emission; hide on a motion layer stops the motion; hide on a sprite keeps its playback clock running (visibility and playback are independent).E6.3 [P] play sprite implies show, and restarts from frame 0 if already playing. Rationale: playing an invisible sprite is never the intent; restart is what "play" means on every media API.E6.4 [P] emit particles implies show, then emits count particles at once. If fewer than count slots are free under maxParticles, the excess is dropped — live particles are never evicted. Rationale: deterministic and allocation-free.E6.5 [P] run motion implies show and restarts from 0 if already running.E6.10 [P] play animation (action 6) implies show of its clip's layer and starts the clip from 0 at that frame — restarting it if it is playing, replacing another clip playing on the same layer, and cancelling the clip's own pending autoplay start (E10.3).E6.6 [P] Continuous emission (type 1) runs at ratePerSecond while the layer is visible. Emission times are t_k = k / ratePerSecond for k = 0, 1, 2, … measured from when emission became active (re-started at 0 on each show), evaluated in whole microseconds as E5.4 (1c) specifies. ratePerSecond: 0 never emits continuously.E6.7 [P] burstCount (type 1) = particles emitted at the instant the layer first becomes active: effect time 0 if visible: true, otherwise at the first show/emit. Only once per effect instance.E6.8 [P] Particle motion is evaluated in closed form, never integrated: p(t) = p0 + v0·t + ½·g·t² with t the particle's age in seconds, v0 = speed × (cos θ, sin θ) and g = (0, gravity), in S units. Every length — speed, gravity, sizeScale — uses the S taken at emission, and the spawn point is the origin at the emission instant (animated, E10.5) × the overlay size at emission. A resized overlay or a moving origin does not move or resize live particles. Rationale: identical positions on any frame rate.E6.9 [P] Spread and randomness. θ = directionDeg − spreadDeg/2 + spreadDeg × r, r ∈ [0, 1). r comes from a mulberry32 stream per layer per instance, seeded with the 32-bit FNV-1a hash of the UTF-8 string "<effectId>:<layerId>", one draw per emitted particle in emission order (dropped particles draw nothing). Angle is the only random quantity in v1. Rationale: without a pinned PRNG, particle layers can never pass a golden test.E7. TimingE7.1 [P] Clock. Effect time = display time since the host's play call. Golden tests supply timestamps directly: effect time is a step's timeMs minus that of the first step.E7.2 [P] startMs (types 2, 3, 5) is measured from effect time 0, and applies only to layers with visible: true at start, which begin automatically at startMs (not drawn before). A layer started by an action (play sprite / run motion) starts at that action; its startMs is ignored. Rationale: the existing timing rules (timing.exceeds_duration) check startMs against the effect timeline, so that is what it means.E7.3 [P] Everything in an effect is cut at durationMs: an action-started motion or sprite that would overrun stops there, and live particles vanish. At durationMs the engine evaluates effect.ended triggers, then tears the instance down; nothing renders after, and the host's "effect finished" callback (§4.2) fires. Actions on effect.ended therefore have no visible result in v1 — the editor should warn about them. Rationale: hosts key cooldowns to durationMs (§3.2); an effect must never outlive it.E7.4 [P] A host stopping an effect early ends it immediately without firing effect.ended.E7.5 [S] §4.2 — The SDK does not transport effect events; the host moves them and calls play on each device.E8. Motion (type 3)Let τ = t / 1000 seconds since the motion started, D its durationMs, f = frequencyHz, I = intensity, e = 1 − t / D a linear decay envelope.E8.1 [P] Shake (1): displaces all other layers of the same effect instance — types 1, 2, 4 and 5; a flash fill (E8.2) is excluded — by d = I · e · 0.03 S · (sin(2π f τ), sin(2π · 0.8 f · τ + π/3)). At I = 1 the peak is 3 % of the short side. The overlay cannot move the host's UI (§4.2 places it above the UI), so SDKs may also expose d(t) to the host, but golden tests cover the overlay only. A flash fill always covers the whole overlay and is never displaced or scaled.E8.2 [P] Flash (2): draws, at its own array position, a full-overlay white fill with alpha I · (0.5 − 0.5 cos(2π f τ)) — f flashes per second, each starting and ending at 0. Rationale: frequencyHz then is the flash rate; the flashing-limit profile rule counts these cycles in any one-second window, all flash motions together (rule-profiles-v1 §5).E8.3 [P] Pulse (3): scales all other layers of the instance (types 1, 2, 4 and 5; not the flash fill) about the overlay centre by 1 + 0.10 · I · e · (0.5 − 0.5 cos(2π f τ)). A flash fill always covers the whole overlay and is never displaced or scaled.E8.4 [P] Several running motions combine: shake displacements add; pulse scales multiply; the transform applies as scale then translate. A hidden motion has no effect.E9. Other gaps a renderer needs pinnedE9.1 [P] Initial state. At start every layer takes its manifest visible; motions, sprites, emitters and clips are idle except as E6.6, E6.7, E7.2 and E10.3 start them.E9.2 [P] Particle cap is per layer (maxParticles) per instance; the cross-layer 300 total is a validation rule (particles.too_many), not a runtime pool.E9.3 [P] Forward path for fields. Because parsing is strict, a field added after the tag must come with a field-level engine level (an EFFECT_ENGINE_LEVEL_BY_FIELD table alongside EFFECT_ENGINE_LEVEL_BY_LAYER_TYPE and EFFECT_ENGINE_LEVEL_BY_EVENT_SOURCE, feeding the computation of minEngineVersion), so an older SDK reports "engine too old" instead of "invalid manifest". No manifest change — a rule for how the editor computes minEngineVersion.E9.4 [P] Rendering is per frame and stateless apart from sprite clocks, motion clocks, pending startMs starts, particle pools with their emission state, PRNG streams, and each layer's playing clip with its start time and the pending autoplay starts (E10.6) — the full list of per-instance state an SDK keeps.E10. Keyframe animationA clip (animations[], effect-manifest-v1.md Animations) animates one layer. Its tracks hold numeric keys; a playing clip's values replace the layer's resting values. Face lenses use E10.1–E10.3 as they stand, on lens time (rendering-v1.md §11).E10.1 [P] Value at a moment. For a track at clip time c (ms): before the first key, the first key's value; after the last key, the last key's value; between keys a and b, u = (c − a.atMs) / (b.atMs − a.atMs) and value = a.value + (b.value − a.value) · ease_a(u), where ease_a is key a's easing. A property with no track in the playing clip — or on a layer with no playing clip — takes its resting value: the layer's own field (position.x, position.y, scale, rotationDeg, opacity, or origin.x / origin.y for particles), and 1 for a full-screen sprite's opacity and zoom. Rotation interpolates the raw degrees (no wrap). Easings may overshoot (back): when a value is used, an opacity is clamped to [0, 1] and a scale or zoom to ≥ 0; x, y and rotation are used as they are.E10.2 [P] Easing, u ∈ [0, 1]:

Easing

ease(u)

1 linear

u

2 ease in

u²

3 ease out

1 − (1 − u)²

4 ease in-out

2u² for u < 0.5, else 1 − (−2u + 2)² / 2

5 hold

0 (the value jumps at the next key)

6 back

1 + 2.70158 (u − 1)³ + 1.70158 (u − 1)² (overshoots, then settles)

7 bounce

with n = 7.5625, d = 2.75: n u² for u < 1/d; n (u − 1.5/d)² + 0.75 for u < 2/d; n (u − 2.25/d)² + 0.9375 for u < 2.5/d; else n (u − 2.625/d)² + 0.984375

E10.3 [P] Clip clock.

An autoplay clip starts at startMs (absent = 0) of effect time, with its clock at startMs (not at the frame time), whether or not its layer is visible — a scheduled start, as E7.2.

play animation (E6.10) starts its clip at the frame time t (clock 0 at t) and cancels that clip's pending autoplay start.

The clock runs whether or not the layer is visible.

Clip time: c = elapsed, or elapsed mod durationMs when loop is true.

A non-looping clip ends when elapsed ≥ durationMs: with endBehavior 1 its values hold at c = durationMs for the rest of the effect; with 2 the clip stops and the layer takes its resting values.

One clip per layer: starting a clip replaces the one playing on its layer; properties the new clip does not animate return to rest at once.

E10.4 [P] Frame order (E5.4). Autoplay starts are scheduled starts (step 1a); clip ends are clock advances (step 1b); play animation runs with the other actions (steps 2–3); drawing (step 5) evaluates every layer's values at t.E10.5 [P] What the values change.

Images and positioned sprites (types 4, 5) draw at their animated x, y, scale, rotationDeg and opacity (E3.1).

A full-screen sprite (type 2): its fitted quad (E2.6) is scaled about the overlay centre by the animated zoom, and drawn with the animated opacity.

Particles (type 1): a particle spawns at the origin evaluated at its own emission instant — t_k for continuous emission (including catch-up, E5.4 (1c)), the frame time t for a burst or an emit. Catch-up evaluates each t_k against the clips as they stood at t_k: plays of earlier frames and autoplay starts scheduled at or before t_k count, and a clip that ends after t_k still plays at t_k; this frame's actions come later. A particle never moves with the origin after its emission (E6.8).

Shake and pulse (E8.1, E8.3) apply after the animated values; the flash (E8.2) is unchanged.

The durationMs cut (E7.3) ends every clip with the effect. Rationale: evaluating the origin at each emission instant keeps particle pools identical at any frame rate, as E5.4's whole-microsecond instants do.

E10.6 [P] State. Per layer: the playing clip and its start time (the clip history back to the previous frame, for E10.5's catch-up), and the pending autoplay starts.Golden testsGolden scenarios live in packages/render/fixtures/scenarios/effect/*.json: confetti-shake (particles under a shake, E8.1), continuous-emission-cap (whole-microsecond emission at the cap, E5.4 (1c)), placed-layers (E3.1), shake-pulse-placed (E3.3), and for keyframes animation-easings (E10.2), animation-clips (E10.3), animation-origin (E10.5) and animation-under-shake (E10.5, E8.1). The "Scenario fixtures" section of packages/render/README.md describes the same file shape, which lens and screen effect scenarios share. Every renderer (the editor preview and the iOS and Android SDKs) replays them and must agree.A scenario file is { description, manifest, assets, seed, steps: [{ input, expect }] }:

manifest — a valid effect manifest v1.

assets — the pixel size of each image the manifest names: { "<asset name>": { "width": 256, "height": 128 } }.

seed — for each particle layer, fnv1a32("<effectId>:<layerId>") (E6.9), so a renderer can check its hash before replaying.

steps — replayed in order on one instance. input is { kind: 2, timeMs, overlaySize, hostEvents }: kind is always 2 for a screen effect. The effect renderer and the lens renderer in packages/render share one runtime, and kind: 2 tells it that this step overlays the effect on the host's UI, at overlaySize, instead of drawing on a camera frame. overlaySize is { width, height } in points, and hostEvents are the host events that arrived since the previous step (those given to the first step arrived before the start and are dropped, E5.2). Effect time is timeMs minus the first step's timeMs (E7.1).

expect — the step's draw list, back to front (E4.1), with numbers rounded to 3 decimals. Effects use two draw commands and never emit lut:

{ op: 'quad', layerId, asset, frameIndex, src, corners, opacity } — src is the rectangle of the asset to draw, in asset pixels (the whole image, or the sprite cell); corners are the destination corners in overlay points, in the order top-left, top-right, bottom-right, bottom-left, with rotation and the screen-motion transform applied; frameIndex is the sprite cell number, or null for a layer that is not a sprite.
{ op: 'fill', layerId, color, alpha } — a full-overlay fill (a screen flash, E8.2); color is sRGB-encoded RGB, each channel in [0, 1], and alpha is its opacity.

A renderer passes a step when every number in its draw list is within 0.002 of the expected value and everything else is exact: op, layerId, asset, frameIndex (including null), object keys and list lengths.