← Lab · · 5 min read
Pausing when off screen, capping the pixel ratio, surviving a lost WebGL context, respecting reduced motion and cleaning up after itself. The runtime every effect in the Lab plugs into, with the code.
Every effect in the Lab is two files. One is the effect: the drawing, and nothing else. The other is this, the runtime it plugs into. It’s the boring half, and it’s the half that decides whether an effect is fit to put on a real website or only fit for a demo page.
This guide is that runtime, what it does and why. The other guides link here rather than repeating it.
An effect is a Surface: four functions. setup when it mounts, resize when its box changes, render to draw a frame at a given time, and teardown to let go of everything. The runtime calls them. The effect never touches requestAnimationFrame, never adds a resize listener, never decides whether it should be running.
import { mount } from './beamish/shared/runtime';
export function createMyEffect(el: HTMLElement, opts = {}) {
return mount(el, opts, {
defaults: { speed: 1 },
kind: 'canvas', // or 'dom' for text and layout effects
create: () => ({
setup({ canvas }) {
/* get a context, compile shaders */
},
resize(size) {
/* size.pixelWidth, size.pixelHeight, size.dpr */
},
render(t, opts, pointer, scroll) {
/* draw the frame at t seconds */
},
teardown() {
/* release everything */
},
}),
});
}
What you get back is a handle with start(), stop(), update(options), renderAtTime(t) and destroy(). That’s the whole public surface of every effect.
It stops when nobody can see it. An intersection observer pauses the loop when the effect scrolls off screen and resumes it when it comes back. A visibility listener does the same when the tab is hidden. A page with three WebGL effects on it costs nothing for the two you’ve scrolled past.
There’s a detail in there that took me a while to find. The observer watches the effect’s parent, not the effect itself. A reveal effect starts with its own box clipped to nothing, the observer reports that as off screen, the loop stops, and the clip never advances. Blank for ever. The parent is laid out by the page, so it can’t deadlock.
It caps the pixel ratio at 2. A phone with a pixel ratio of 3 asks a canvas for nine times the pixels of a ratio of 1. Above 2 the cost is real and nobody can see the difference.
It respects reduced motion, properly. If someone has reduced motion switched on, there’s no loop at all, not a slower one. The effect draws one composed frame and stops. It listens for the setting changing mid-session too, so turning it on takes effect without a reload.
It survives losing the GPU. Chrome takes WebGL contexts back from pages more often than you’d think, not only when the GPU crashes. The runtime catches the loss, tears the effect down, and builds it again when the context comes back. Without this, a canvas quietly goes black and stays black.
It never shows a black flash. A WebGL canvas starts out opaque black, and resizing it resets it to black. The canvas is hidden until it has a frame in it, and every resize redraws immediately rather than waiting for the next tick.
It cleans up after itself. destroy() removes every listener, disconnects both observers and hands the WebGL context back to the browser straight away. Browsers allow around sixteen live contexts, so a site that navigates between pages with effects on will hit the limit without this.
This is the decision everything else rests on. render is handed t, the seconds since the effect started, and it has to draw the same picture every time it’s handed the same t. No accumulating state between frames, no Math.random() per frame.
That sounds like a constraint for its own sake. It’s what makes the effects recordable: I can ask for frame 90 and get frame 90, which is how every poster and video on beamish.ink was made. It means pausing and resuming never jumps. And it makes bugs reproducible, because a frame that looks wrong will look wrong again.
The one input that can’t be pure is the real scroll position, so it’s sampled once per frame inside the loop rather than on the scroll event. Scroll events arrive about six times a second while the effect draws at sixty, so anything driven by the event moves in steps. Reading the box every frame costs about twenty microseconds.
The second file is small. Any colour option can be set to auto, which means “whatever the page behind me is”, or light-dark(#fff, #000), which picks one or the other depending on whether that page is light or dark. It walks up from the effect to the first ancestor that actually paints a background, so an effect dropped onto a dark section picks up the dark section without being told.
Both files, as they run on this site.
/*
* Beamish effect runtime.
*
* Every tier-1 effect is a thin `Surface` plugged into `mount()`. The host owns
* everything that is the same for all of them and easy to get wrong: DPR capping,
* resize, pausing offscreen, pausing on tab hide, reduced motion, WebGL context
* loss and restore, and full teardown.
*
* An effect's core.ts should contain drawing, and nothing else.
*/
import { resolveAutoGrounds } from './ground'
export type EffectHandle = {
start(): void
stop(): void
update(opts: Record<string, unknown>): void
/** Deterministic: the same `t` must always yield the same frame. */
renderAtTime(t: number): void
/** Release the WebGL context, RAF and every listener. */
destroy(): void
}
export type Size = {
/** CSS pixels. */
width: number
height: number
/** Device pixels, DPR already capped. Use these for the drawing buffer. */
pixelWidth: number
pixelHeight: number
dpr: number
}
export type Pointer = {
/**
* 0 to 1 across the element, origin top-left. Centre until first move.
*
* Under `pointerScope: 'window'` this is not clamped: 1.4 means the cursor is
* 40% of the element's width past its right edge. An effect that reaches
* beyond its own box needs to know how far.
*/
x: number
y: number
/** False until the pointer has entered, so effects can idle sensibly. */
active: boolean
}
/** One sample of a scripted cursor path. `t` is seconds; x/y are 0 to 1. */
export type PointerKey = { t: number; x: number; y: number }
/**
* One scripted press. `t` is seconds from the start of the loop; x/y are 0 to 1
* across the element.
*
* A path can say where the cursor is at any moment, but a press is an instant
* rather than a position, so it needs its own list. An effect that answers to
* clicks reads this alongside whatever real presses it has seen, which is what
* lets the recorder produce a take with clicks in it without anything having
* been clicked.
*/
export type PressKey = { t: number; x: number; y: number }
export type Scroll = {
/**
* How far the host has travelled through the viewport. 0 when its top edge is
* level with the bottom of the viewport, 1 when its bottom edge is level with
* the top. Outside that range the element is off screen.
*/
progress: number
/**
* Signed rate of change of `progress`, in units per second, already smoothed.
* Negative is scrolling back up.
*
* This is the interesting one. Position tells an effect where it is; velocity
* tells it how hard it was thrown, which is what anything physical has to know.
*/
velocity: number
/** False until the page has actually been scrolled. */
active: boolean
}
/** One sample of a scripted scroll path. `t` is seconds; progress is 0 to 1. */
export type ScrollKey = { t: number; progress: number }
export type SurfaceContext = {
/** The element the effect was mounted into. */
host: HTMLElement
/**
* The generated canvas, or null for a `kind: 'dom'` effect. A text treatment
* has nothing to draw into and should not be handed a canvas it will not use.
*/
canvas: HTMLCanvasElement | null
size: Size
}
/**
* The per-effect half. `setup` runs on mount and again after the GPU hands the
* context back, so it must be safe to call more than once.
*/
export interface Surface<O> {
setup(ctx: SurfaceContext): void
resize(size: Size): void
/**
* Draw one frame. `t` is absolute seconds from the start of the loop.
*
* Must be pure in `t`. Do not integrate against the previous frame, or the
* recorder cannot produce a clean loop and `renderAtTime` breaks.
*/
render(t: number, opts: O, pointer: Pointer, scroll: Scroll): void
teardown(): void
/** Return the GL context if there is one, so the host can release it. */
context?(): WebGLRenderingContext | WebGL2RenderingContext | null
}
export type BaseOptions = {
/**
* Scripted cursor path. When set, the live pointer is ignored and the pointer
* is sampled from this path at the current time, which is what makes
* pointer-driven effects deterministic for the recorder.
*/
pointerPath?: PointerKey[]
/** Seconds the scripted path takes to run once before repeating. */
pointerPathDuration?: number
/**
* Scripted presses, for effects that answer to a click. Each is a time and a
* point, and an effect treats them exactly as it treats a real press that
* happened at that moment, so a recorded take and a live page agree.
*
* Unlike `pointerPath`, this does not replace the live input: a scripted press
* and a real one are the same kind of event, and an effect that ignored the
* cursor while a script was running would be dead on the page.
*/
pressPath?: PressKey[]
/**
* Scripted scroll path. When set, the real scroll position is ignored and both
* progress and velocity are read from this path at the current time.
*
* Velocity is the slope of the segment rather than a difference against the
* last frame, so it is a function of `t` alone. That is the whole point: an
* effect driven by a real scrollbar cannot be replayed, and the recorder needs
* frame 90 to look the same every time it asks for it.
*/
scrollPath?: ScrollKey[]
/** Seconds the scripted scroll path takes to run once before repeating. */
scrollPathDuration?: number
/** Frame shown when the user prefers reduced motion. Pick one that composes. */
reducedMotionTime?: number
/** Cap on device pixel ratio. Above 2 the cost is real and the gain is not. */
maxDpr?: number
/** Set false to opt out of pausing when scrolled offscreen. */
pauseWhenOffscreen?: boolean
/**
* Where the pointer is read from.
*
* `element` fires only while the cursor is over the host and reports 0 to 1.
* `window` follows the cursor everywhere and reports element-relative
* coordinates that go outside 0 to 1, which is what an effect needs if it
* reacts to a cursor that has not arrived yet.
*/
pointerScope?: 'element' | 'window'
}
export type MountConfig<O> = {
/** Merged over on every `update()`. */
defaults: O
create(): Surface<O>
/**
* `canvas` generates a canvas filling the host and watches it for context
* loss. `dom` generates nothing and hands the host element straight to the
* surface, which is what a text or layout effect wants.
*/
kind?: 'canvas' | 'dom'
/** Extra classes for the generated canvas. Ignored when kind is 'dom'. */
canvasClass?: string
}
const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)'
const clamp01 = (n: number) => (n < 0 ? 0 : n > 1 ? 1 : n)
/** Linear sample of a scripted path, wrapping at `duration` so it loops. */
export const samplePointerPath = (keys: PointerKey[], t: number, duration: number): Pointer => {
if (keys.length === 0) return { x: 0.5, y: 0.5, active: false }
const first = keys[0]!
if (keys.length === 1) return { x: first.x, y: first.y, active: true }
const span = duration > 0 ? duration : keys[keys.length - 1]!.t
const local = span > 0 ? ((t % span) + span) % span : 0
let a = first
let b = keys[keys.length - 1]!
for (let i = 0; i < keys.length - 1; i++) {
const lo = keys[i]!
const hi = keys[i + 1]!
if (local >= lo.t && local <= hi.t) {
a = lo
b = hi
break
}
}
const gap = b.t - a.t
const k = gap > 0 ? clamp01((local - a.t) / gap) : 0
// Smoothstep between keys: a linear cursor reads as a machine, which is what
// it is, but it looks wrong next to eased motion.
const e = k * k * (3 - 2 * k)
return { x: a.x + (b.x - a.x) * e, y: a.y + (b.y - a.y) * e, active: true }
}
/**
* Linear sample of a scripted scroll path, wrapping at `duration` so it loops.
*
* Velocity comes out of the same smoothstep by differentiating it rather than by
* comparing against the previous frame, which is what keeps the whole thing a
* function of `t`. The derivative of the smoothstep is 6k(1-k), so velocity is
* zero at each key and peaks halfway between: the scroll eases in and out of
* every stop by construction.
*/
export const sampleScrollPath = (keys: ScrollKey[], t: number, duration: number): Scroll => {
if (keys.length === 0) return { progress: 0, velocity: 0, active: false }
const first = keys[0]!
if (keys.length === 1) return { progress: first.progress, velocity: 0, active: true }
const span = duration > 0 ? duration : keys[keys.length - 1]!.t
const local = span > 0 ? ((t % span) + span) % span : 0
let a = first
let b = keys[keys.length - 1]!
for (let i = 0; i < keys.length - 1; i++) {
const lo = keys[i]!
const hi = keys[i + 1]!
if (local >= lo.t && local <= hi.t) {
a = lo
b = hi
break
}
}
const gap = b.t - a.t
const k = gap > 0 ? clamp01((local - a.t) / gap) : 0
const e = k * k * (3 - 2 * k)
const delta = b.progress - a.progress
return {
progress: a.progress + delta * e,
velocity: gap > 0 ? (delta * 6 * k * (1 - k)) / gap : 0,
active: true
}
}
export function mount<O extends BaseOptions>(
el: HTMLElement,
userOpts: Partial<O> | undefined,
config: MountConfig<O>
): EffectHandle {
/*
* `auto` in a colour option means take it from the page. Resolved here, at
* the one point that has both the host element and the merged options, so no
* item has to reach into the DOM from inside its own render loop.
*/
let opts: O = resolveAutoGrounds(el, { ...config.defaults, ...(userOpts ?? {}) })
const kind = config.kind ?? 'canvas'
let canvas: HTMLCanvasElement | null = null
if (kind === 'canvas') {
canvas = document.createElement('canvas')
canvas.style.display = 'block'
canvas.style.width = '100%'
canvas.style.height = '100%'
/*
* Its own compositor layer, so the page cannot resample it.
*
* A canvas whose box lands on a half pixel has to be resampled to the
* device grid, and which way it snaps is the compositor's business rather
* than ours. Snapping one way on one frame and the other way on the next
* moves the whole picture by a pixel, which is a flicker between two
* positions that leaves no trace anywhere: the drawing buffer is perfect,
* the clock is smooth, the box never changes and every number comes back
* clean. It was reported on a canvas sitting at x = 683.5, and the same
* effect at x = 123.5 on another machine was steady.
*
* translateZ(0) rather than will-change, because will-change is a hint
* the browser is free to drop and this needs to be a promise. The cost is
* one layer per live effect, and there is only ever one.
*/
canvas.style.transform = 'translateZ(0)'
canvas.style.backfaceVisibility = 'hidden'
/*
* Hidden until the first frame is in it.
*
* A WebGL canvas with `alpha: false` starts opaque black, and it is in the
* document from the moment it is created, so between that and the first
* draw the browser has a black rectangle to paint. On a warm cache that is
* one frame and it reads as a flash; on a cold one the gap is longer.
*
* visibility rather than display, because display: none gives the element
* no size and the first measure would come back zero.
*/
canvas.style.visibility = 'hidden'
if (config.canvasClass) canvas.className = config.canvasClass
el.appendChild(canvas)
}
let surface: Surface<O> | null = null
let size: Size = measure()
let raf = 0
let running = false
let destroyed = false
let contextLost = false
// Wall-clock is accumulated rather than read, so stopping and starting does not
// jump the animation and the loop stays reproducible.
let elapsed = 0
let lastStamp = 0
const pointer: Pointer = { x: 0.5, y: 0.5, active: false }
const scroll: Scroll = { progress: 0, velocity: 0, active: false }
/*
* Scroll is sampled once per frame, in the loop, rather than on the scroll
* event.
*
* The event is the obvious place and it is the wrong one. Measured on a real
* wheel scroll, scroll events arrive at about 6Hz while the effect renders at
* 60, so a value taken on the event is reused for up to five frames running
* and the effect moves in visible steps. Decaying it between events does not
* fix that; it just turns the steps into a sawtooth.
*
* Reading the rect every frame costs about 20 microseconds, measured, which
* is a tenth of a percent of a frame. It is a read with no write in front of
* it, so it forces no layout.
*
* This is the one piece of state in the runtime that is not a function of
* `t`, which is why `scrollPath` exists to replace it wholesale for the
* recorder.
*/
let scrollStarted = false
let scrollSeeded = false
/*
* Half-life of the velocity smoothing. A per-frame difference is noisy enough
* that handing it straight to a shader looks like chatter, and frame times
* are not uniform. 70ms is short enough to feel attached to the input and
* long enough to hide that jitter.
*/
const VELOCITY_HALF_LIFE = 0.07
function sampleScroll(dt: number) {
const rect = el.getBoundingClientRect()
const viewport = window.innerHeight || 1
/*
* 0 when the top edge is level with the bottom of the viewport, 1 when the
* bottom edge is level with the top. Measured against the element's own
* height plus the viewport, so a tall hero and a short strip both travel
* the full range, which is what makes the number worth handing to an
* effect at all.
*/
const span = viewport + rect.height
const next = span > 0 ? clamp01((viewport - rect.top) / span) : 0
if (!scrollSeeded) {
// Nothing to difference against on the first frame, and seeding it with a
// zero gap would read as an infinite velocity.
scroll.progress = next
scrollSeeded = true
return
}
if (dt > 0) {
const instant = (next - scroll.progress) / dt
const k = 1 - Math.pow(0.5, dt / VELOCITY_HALF_LIFE)
scroll.velocity += (instant - scroll.velocity) * k
if (Math.abs(scroll.velocity) < 1e-4) scroll.velocity = 0
}
if (next !== scroll.progress) scrollStarted = true
scroll.progress = next
scroll.active = scrollStarted
}
const motionQuery =
typeof matchMedia === 'function' ? matchMedia(REDUCED_MOTION_QUERY) : null
let reduced = motionQuery?.matches ?? false
function measure(): Size {
const rect = el.getBoundingClientRect()
const width = Math.max(1, Math.round(rect.width))
const height = Math.max(1, Math.round(rect.height))
const cap = opts.maxDpr ?? 2
const dpr = Math.min(window.devicePixelRatio || 1, cap)
return {
width,
height,
pixelWidth: Math.max(1, Math.round(width * dpr)),
pixelHeight: Math.max(1, Math.round(height * dpr)),
dpr
}
}
function applySize() {
size = measure()
if (canvas) {
if (canvas.width !== size.pixelWidth) canvas.width = size.pixelWidth
if (canvas.height !== size.pixelHeight) canvas.height = size.pixelHeight
}
surface?.resize(size)
}
function pointerAt(t: number): Pointer {
const path = opts.pointerPath
if (path && path.length > 0) {
return samplePointerPath(path, t, opts.pointerPathDuration ?? 0)
}
return pointer
}
function scrollAt(t: number): Scroll {
const path = opts.scrollPath
if (path && path.length > 0) {
return sampleScrollPath(path, t, opts.scrollPathDuration ?? 0)
}
return scroll
}
function draw(t: number) {
if (!surface || contextLost) return
surface.render(t, opts, pointerAt(t), scrollAt(t))
// There is something in the canvas now, so it can be shown. Cheap: a style
// write that is already the current value does not invalidate anything.
if (canvas && canvas.style.visibility === 'hidden') canvas.style.visibility = ''
}
function tick(stamp: number) {
if (!running) return
/*
* Clamped at both ends.
*
* The top end is the tab-switch spike this always guarded against. The
* bottom end is that a rAF timestamp is the moment the frame began, which
* can be EARLIER than the performance.now() start() took a moment before:
* the subtraction is then negative, Math.min keeps it, and the effect's
* clock runs backwards. Measured on WindField, elapsed began at -0.1088
* and four frames were rendered at a negative t before it climbed past
* zero. A shader handed a smaller t than last frame draws an earlier
* picture, which is a visible jump backwards on every start, and start
* runs again every time the panel scrolls into view or the tab is
* returned to.
*/
const dt = Math.min(Math.max(stamp - lastStamp, 0), 100) / 1000
elapsed += dt
lastStamp = stamp
sampleScroll(dt)
draw(elapsed)
raf = requestAnimationFrame(tick)
}
function ensureSurface() {
if (surface || destroyed) return
surface = config.create()
surface.setup({ host: el, canvas, size })
surface.resize(size)
}
function start() {
if (destroyed || running || contextLost) return
ensureSurface()
if (reduced) {
// WCAG 2.3.3: no loop at all. Still show a composed frame rather than a
// blank panel. See reducedMotionTime.
draw(opts.reducedMotionTime ?? 0)
return
}
running = true
lastStamp = performance.now()
raf = requestAnimationFrame(tick)
}
function stop() {
running = false
if (raf) cancelAnimationFrame(raf)
raf = 0
/*
* Velocity is sampled in the loop, so a paused effect would otherwise keep
* whatever it was last handed. Resuming after being scrolled past would
* then show one frame of a flick that happened seconds ago.
*/
scroll.velocity = 0
}
// --- context loss ------------------------------------------------------
// Chromium hands a lost context back when an active one is released, so this
// path fires in ordinary use, not only on a GPU crash.
const onLost = (event: Event) => {
event.preventDefault() // without this the context is not recoverable
contextLost = true
stop()
surface?.teardown()
surface = null
}
const onRestored = () => {
contextLost = false
if (destroyed) return
ensureSurface()
applySize()
if (visible) start()
}
// Only a canvas can lose a GL context. A DOM effect has nothing to listen for.
canvas?.addEventListener('webglcontextlost', onLost as EventListener, false)
canvas?.addEventListener('webglcontextrestored', onRestored, false)
// --- pointer -----------------------------------------------------------
const windowScope = opts.pointerScope === 'window'
const onPointerMove = (event: PointerEvent) => {
const rect = el.getBoundingClientRect()
if (rect.width === 0 || rect.height === 0) return
const x = (event.clientX - rect.left) / rect.width
const y = (event.clientY - rect.top) / rect.height
// Window scope reports unclamped coordinates on purpose. An effect that
// reaches past its own edge has to know how far past, and clamping would
// pin it to the border instead.
pointer.x = windowScope ? x : clamp01(x)
pointer.y = windowScope ? y : clamp01(y)
pointer.active = true
}
const onPointerLeave = () => {
pointer.active = false
}
const pointerTarget: EventTarget = windowScope ? window : el
pointerTarget.addEventListener('pointermove', onPointerMove as EventListener)
// Only element scope has a leave: the window one is never left.
if (!windowScope) el.addEventListener('pointerleave', onPointerLeave)
// --- scroll ------------------------------------------------------------
/*
* No scroll listener. The position is read in the frame loop above, which is
* both smoother and one fewer thing to remove on teardown. An effect that is
* not running does not need a scroll position, because nothing is drawing it.
*/
// --- visibility and viewport -------------------------------------------
let visible = true
let wantedByUser = false
const resizeObserver = new ResizeObserver(() => {
if (destroyed) return
applySize()
/*
* Always redraw, not only when stopped.
*
* Assigning canvas.width or canvas.height resets the drawing buffer, and a
* WebGL buffer resets to opaque black. Leaving that for the next animation
* frame means one black frame every time the element changes size, and
* since the observer fires once on its first observation, that was a black
* flash on every mount: the canvas showed its first drawn frame, the
* observer cleared it, and the page painted the hole before the next tick
* filled it.
*/
draw(reduced ? opts.reducedMotionTime ?? 0 : elapsed)
})
resizeObserver.observe(el)
const intersectionObserver =
opts.pauseWhenOffscreen === false
? null
: new IntersectionObserver(
entries => {
const entry = entries[entries.length - 1]
if (!entry) return
visible = entry.isIntersecting
if (visible) {
if (wantedByUser) start()
} else {
stop()
}
},
{ threshold: 0 }
)
/*
* The gate watches the element's parent, not the element.
*
* Watching the element deadlocks any effect that clips or moves its own host.
* A reveal starts with its host clipped to nothing, the observer reports that
* as not intersecting, the runtime stops the loop, and the clip therefore
* never advances off the host: blank for ever, with the replay button unable
* to escape it because `visible` can never become true again. The gate's
* input must not be geometry the effect controls.
*
* The parent is laid out by the page rather than by the effect, so it breaks
* the cycle. It is usually a little larger, which means an effect can start a
* frame or two before it is strictly on screen. That is the cheaper mistake.
*/
intersectionObserver?.observe(el.parentElement ?? el)
const onVisibilityChange = () => {
if (document.hidden) stop()
else if (wantedByUser && visible) start()
}
document.addEventListener('visibilitychange', onVisibilityChange)
// Live listener, not a one-time read, so toggling the OS setting mid-session
// takes effect without a reload.
const onMotionChange = (event: MediaQueryListEvent) => {
reduced = event.matches
if (reduced) {
stop()
ensureSurface()
draw(opts.reducedMotionTime ?? 0)
} else if (wantedByUser && visible) {
start()
}
}
motionQuery?.addEventListener('change', onMotionChange)
// --- handle ------------------------------------------------------------
const handle: EffectHandle = {
start() {
wantedByUser = true
if (visible && !document.hidden) start()
},
stop() {
wantedByUser = false
stop()
},
update(next) {
opts = resolveAutoGrounds(el, { ...opts, ...(next as Partial<O>) })
applySize()
if (!running) draw(reduced ? opts.reducedMotionTime ?? 0 : elapsed)
},
renderAtTime(t) {
if (destroyed) return
ensureSurface()
elapsed = t
draw(t)
},
destroy() {
if (destroyed) return
destroyed = true
stop()
motionQuery?.removeEventListener('change', onMotionChange)
document.removeEventListener('visibilitychange', onVisibilityChange)
intersectionObserver?.disconnect()
resizeObserver.disconnect()
pointerTarget.removeEventListener('pointermove', onPointerMove as EventListener)
el.removeEventListener('pointerleave', onPointerLeave)
canvas?.removeEventListener('webglcontextlost', onLost as EventListener)
canvas?.removeEventListener('webglcontextrestored', onRestored)
const gl = surface?.context?.() ?? null
surface?.teardown()
surface = null
// Hand the context back now rather than waiting for GC. The browser budget
// is 16 contexts or 16M pixels, whichever comes first, and a page that
// navigates between demos will hit it otherwise.
gl?.getExtension('WEBGL_lose_context')?.loseContext()
canvas?.remove()
}
}
return handle
}
/*
* What is actually behind this effect, and what to paint on it.
*
* Items that paint their own ground used to default it to #fbfaf4, the warm
* paper the site happened to be. That one default is most of what made the
* library a paper library: an effect dropped onto a dark page painted a cream
* rectangle over it and looked broken, so in practice it only worked on one
* kind of page, whatever its metadata said.
*
* Two words fix that, and they are deliberately the two CSS already has.
*
* `auto` is the page's own background. The item adopts whatever it has been
* put on, which is what people expected a default to do.
*
* `light-dark(a, b)` is a colour chosen by the ground it will sit on, spelled
* the way the CSS function of the same name spells it. This is for the marks
* rather than the ground, and it exists because deriving them does not work:
* taking the mark colour from the page's text gave pure black on paper, which
* this library does not use as ink, and still left the marks invisible on
* black. A mark colour is a design decision for each ground, so the item makes
* both decisions and the page picks.
*
* Neither costs anything to adopt. On a paper page `auto` resolves to
* rgb(251, 250, 244), which is #fbfaf4 to the byte, and `light-dark()` returns
* its first value, so an item keeps exactly the rendering it had and no
* recorded take is invalidated.
*/
/** The first real background painted at or above `el`, as `rgb(r, g, b)`. */
export function pageGround(el: HTMLElement): string {
for (let node: Element | null = el; node; node = node.parentElement) {
const colour = getComputedStyle(node).backgroundColor
if (isPainted(colour)) return colour
}
/*
* Nothing in the chain paints. The root still has a used value even when no
* stylesheet sets one, and it is what the viewport is actually showing.
*/
const root = getComputedStyle(document.documentElement).backgroundColor
if (isPainted(root)) return root
const body = document.body && getComputedStyle(document.body).backgroundColor
if (body && isPainted(body)) return body
// A page that paints nothing is a white page, which is what the browser draws.
return 'rgb(255, 255, 255)'
}
/**
* An option that may be a colour or the string `auto`.
*
* Anything that is not `auto` is handed back untouched, so passing a colour
* still wins and nothing has to know whether the default was taken.
*/
export function resolveGround(el: HTMLElement, value: string): string {
return value.trim().toLowerCase() === 'auto' ? pageGround(el) : value
}
/** Whether a ground is dark enough to want light marks on it. */
export function isDarkGround(colour: string): boolean {
return relativeLuminance(colour) < 0.5
}
/**
* Resolve the ground-dependent options against the page, once, at mount.
*
* Done here rather than in each item because there is nothing item-specific
* about it. Fifteen effects paint a ground and each reads its option in its
* own shape, as a uniform, a THREE.Color, a cached vector or a scene
* background, so patching them one at a time would be fifteen chances to put
* a getComputedStyle inside a render loop. The runtime already holds the host
* element and already merges the options, so it is the one place that knows
* both.
*
* It runs on update too, which is what makes a ground change at runtime work:
* re-pass the option and the item picks up the new page.
*/
export function resolveAutoGrounds<O extends object>(el: HTMLElement, opts: O): O {
let ground: string | null = null
let next: Record<string, unknown> | null = null
// Read the page at most once, however many options end up asking for it.
const page = () => (ground ??= pageGround(el))
const write = (key: string, value: string) => {
next ??= { ...(opts as Record<string, unknown>) }
next[key] = value
}
for (const [key, value] of Object.entries(opts)) {
if (typeof value !== 'string') continue
const text = value.trim()
const word = text.toLowerCase()
if (word === 'auto') {
write(key, page())
continue
}
if (word.startsWith('light-dark(')) {
const pair = splitPair(text)
if (pair) write(key, isDarkGround(page()) ? pair[1] : pair[0])
}
}
return (next ?? opts) as O
}
/*
* The two arguments of light-dark(...), split on the comma that is not inside
* a nested function, so rgb(0, 0, 0) survives being an argument.
*/
function splitPair(text: string): [string, string] | null {
const open = text.indexOf('(')
const close = text.lastIndexOf(')')
if (open < 0 || close < open) return null
const inner = text.slice(open + 1, close)
let depth = 0
for (let i = 0; i < inner.length; i++) {
const ch = inner[i]
if (ch === '(') depth += 1
else if (ch === ')') depth -= 1
else if (ch === ',' && depth === 0) {
return [inner.slice(0, i).trim(), inner.slice(i + 1).trim()]
}
}
return null
}
/*
* Transparent is not a colour the effect can paint with, and neither is a
* fully transparent rgba, which is what every element that sets no background
* computes to. Both mean "keep looking up the tree".
*/
function isPainted(colour: string): boolean {
if (!colour || colour === 'transparent') return false
const parts = colour.match(/[\d.]+/g)
if (!parts) return false
// rgba(...) with a fourth component of 0.
return !(parts.length >= 4 && Number(parts[3]) === 0)
}
/** WCAG relative luminance, 0 to 1, from a hex or rgb() string. */
function relativeLuminance(colour: string): number {
const [r, g, b] = toRgb(colour)
const channel = (value: number) => {
const c = value / 255
return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
}
return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
}
function toRgb(colour: string): [number, number, number] {
const text = colour.trim()
if (text.startsWith('#')) {
const hex =
text.length === 4
? text[1]! + text[1]! + text[2]! + text[2]! + text[3]! + text[3]!
: text.slice(1, 7)
const n = Number.parseInt(hex, 16)
return Number.isNaN(n) ? [255, 255, 255] : [(n >> 16) & 255, (n >> 8) & 255, n & 255]
}
const parts = text.match(/[\d.]+/g)
if (!parts || parts.length < 3) return [255, 255, 255]
return [Number(parts[0]), Number(parts[1]), Number(parts[2])]
}
It’s TypeScript with no dependencies, and it’s MIT licensed. Copy both files into your project, keep the folder structure (shared/runtime.ts and shared/ground.ts), and the effect guides in the Lab drop straight in next to them. In Astro it works from a plain <script>. In React it goes in a useEffect that calls destroy() on the way out.
If you’d rather I built the whole thing, that’s the day job.
Other posts on the same ground.
