Image lid

One sentence: the real img is never hidden and never moved; an effect is one opaque canvas laid over it for as long as the effect runs, drawn from a copy of the image made at the canvas’s own pixel size; taking the canvas off is the rest state and every failure path.

When to use

• A picture that arrives through something only a shader does: a rough front with material behind it, a dissolve pixel by pixel, cells that resolve.
• A gallery, a listing, a card grid: pictures that come into view.
• A treatment the CSS engine cannot make: one sample a cell, whole round dots, a dithered reveal.

Do not use it for:

• An image in view at load. An arrival is for what comes in; covering what is already there withholds it.
• A figure inside running prose. Nothing moves beside the text unless the reader starts it.
• Images with transparency, or on a ground that is not flat. The lid is opaque.
• Anything the CSS engine already does well enough. A context is the scarce thing.

Rules

1. Never hand an img to texImage2D. It froze the page for a tenth of a second or more per image. Make an ImageBitmap off the main thread, cropped to what object-fit shows and resized to the lid’s pixel size, when the image is near; upload that, which takes 4 to 12 ms.
2. The texture is made at the lid’s size. A full-size texture minified with linear filtering does not match the picture (13 percent of pixels off by more than 2 levels, small text broken up). A bitmap resized to the lid matched to within a few levels.
3. Size the backing store from devicePixelContentBoxSize where it exists, with rounding as the fallback, and fade the lid on and off rather than cutting: on fractional pixel ratios a rounded lid was off by up to 103 levels on a tenth of its pixels. Cancel every animation on a canvas when the pool takes it back and again when it lends it. The fade that takes a lid off fills forwards; left on the canvas, it held the next picture’s lid at opacity 0: a lid on, drawing, that nobody could see. On the owner’s bench it read as pictures answering at random, and a check that counts canvases cannot see it; the checks read the canvas’s computed opacity.
4. Snap the pixel-ratio cap to a whole fraction of device pixels. A lid pixel that is 1.33 device pixels smears every cell.
5. Draw the first frame before the canvas is seen. Insert it hidden, read the tokens, draw, then show it. The first frame is the treated picture or the ground, never nothing.
6. The lid is opaque and paints the ground. Because the image under it is never hidden, nothing the script does can leave a hole; the worst outcome is a lid that has to come off.
7. Wind a rescue animation back every frame. A compositor opacity animation, delayed by rescueMs, takes the lid off by itself if frames stop coming. Measured: lids gone 3.1 s into a 7 s block.
8. Cover one lid per frame, page-wide. A cover costs 4 to 35 ms of main thread.
9. A row arrives whole or arrives plain. Images that enter together are grouped by row; the first row takes the lids there are, a later row that cannot be covered whole arrives plain. A row half treated was seen in the research and is worse than either.
10. A bitmap that comes after its image entered still covers it, late and faded on. On a 2x screen or a slower machine some of a row’s bitmaps resolve after a fast scroll has brought the row in; dropping those left one plain tile among treated neighbours, at random. Two things follow. Entering never waits on “near”: the two observers report in no promised order, and inside an iframe the root margin that makes near come first is not applied, so a row jumped to was entered first, turned away, and never asked again. And an image is in the waiting group once: handed in at entry and again when its bitmap came, a row of three counted as six, more than the lids there are, and was left plain for good.
11. Pool the contexts. Sixteen per page in Chrome and Safari, eight on Android, shared with every other tab of the site. Lend a canvas for the length of an effect, give it back, lose its context after four idle seconds. Never above six live.
12. On context loss, drop; never restore. The lid comes off, the entry is dropped, the next effect makes a new one.
13. Stop on beforeprint, on hiding, on the image’s resize, and on any exception in the loop. All of them remove every lid of the mount.
14. Never add crossorigin. It turns a working image into a broken one when the server is not set up for it. Upload inside try; an image that cannot be read is left plain and never tried again.
15. Once. Each image arrives once per page load, the first time it is seen. Not on scrolling back.
16. A lid driven by input ends on a rest test in device pixels, never on a timer. The pointer is gone, or the page is under its dead zone, and the largest displacement is under half a device pixel. A threshold on the drive itself kept lids on for seconds showing nothing. Its first frame is the plain picture, so it goes on invisibly; it answers every time, not once.
17. Scroll is read, never written. No smooth-scroll library, no wheel handler, no preventDefault, no transformed wrapper. The speed comes from the scroll events themselves, differenced between consecutive events, so a flick after a long rest is measured from its own first two events. A test holds the file to it.
18. Mouse and pen only. A touch pointer starts nothing: there is no hover. And presence is read from the pointer’s last known position against the picture’s box every frame, never from an enter and leave pair: a leave that never comes kept a lid present for good. A cancel, a blur or an exit of the window is the pointer gone.
19. A hover lid goes only on a thumbnail that is a link, where a hover means “about to open”. Never on a picture the reader inspects: the pointer rests on exactly the thing being read. A lid driven by scroll speed is off by default on a real page: a lid per visible picture, for a reader who is scanning.
20. A lid recipe declares its own VERTEX and draws. The region compiles the declared vertex shader and calls draws(gl, at, options) for the first frame and every frame after; most recipes draw one triangle, a point recipe draws the ground then its points.
21. A lid recipe says whether a picture in view at mount arrives. COVERS_IN_VIEW is false for a gallery recipe, where an arrival is for what comes in and a flick produces none, and true for a hero recipe, whose picture is on screen at load.

Decisions

Tuning

Ranges are from the research’s stills. Motion has not been tuned by eye.

Rest state

The plain img, with no canvas in the document. The same under reduced motion (nothing is created), without WebGL2 or createImageBitmap, on a software renderer, when the pool is spent, when the image cannot be read, in print, and after the effect.

Cost

• To build: the lid once, medium: most of it is the failure paths. Each effect on top is a fragment of under forty lines and a few uniforms.
• To run, measured on one integrated GPU (AMD Radeon 610M, Chrome 154): a new lid costs about 35 ms of main thread for a 1440 by 900 one (getContext 18 ms median, 55 worst, compile and link 4 ms, upload 12 ms), a pooled one 4 to 12 ms; per frame while live, 0.1 to 0.2 ms of script for four to eight lids. Memory per live lid at 720 by 450 CSS px on a 2x screen: about 21 MB; capped at 1.5, about 12. Nothing after the handover. The lid region is about 3 kB gzipped of each recipe that carries it.
• To the reader: the picture is covered or distorted for the length of the effect. On an arrival that is a delay before it can be read; under a pointer it is worse, which is why a hover may only go on a thumbnail that is a link.

Checklist

• The budget check passes and harness-drift holds the lid region.
• npm run check:browser: lids go on, at most the cap at once, and no picture under one is hidden or moved.
• npm run check:browser: at the end the lid matches the picture to within 8 levels on under 2 percent of pixels.
• npm run check:browser: with the loop stalled the lids are gone inside 3.5 s.
• npm run check:browser: a row is covered whole or not at all.
• npm run check:browser: reduced motion makes no bitmap; a cross-origin image is left plain; beforeprint and a lost context take lids off.
• Looked at once on the stage at phone size, and once with the 30 fps preview.
• Run once in Safari (no devicePixelContentBoxSize), once in Firefox, and once on a 125 percent Windows screen before it is marked passed.

Recipes

• shader-lift: a treatment lifted off a picture, pixel by pixel.
• plane-arrive: a rough front uncovers a picture from the edge it entered by.
• point-lift: a picture arrives as its own points; the lid form with a point draw.
• plane-press: the driven form, carrying its region; a linked thumbnail answers the pointer.
• plane-bend: pictures trail their edges while the page moves fast; a lab experiment.

Sources

• mdn-webgl-textures: why a cross-origin image cannot be a texture, and the trap of adding crossorigin
• bcd-createimagebitmap: support for the bitmap resize that makes the handover exact
• webgl2fundamentals-multiple-views: why contexts are the scarce thing
• chromium-review-android-contexts: the cap of eight on Android
• nng-animation-duration: where a transition starts to read as delay