Gmira Canvas

Canvas

The GPU floor. Impeccable ships numeric floors for type, color, layout, and motion, and none for GPU work. These are ours, and they are checks on the built result.

Load ../gmira/references/DOCTRINE.md (Part 4 is this floor). Code for every pattern below: ../gmira/references/canvas-primitives.md (14 lifted primitives) and ../gmira/references/canvas-craft-rules.md.

Decide before you shade

Three questions, answered in writing, before a single line of GLSL.

1. What does this effect communicate? Not "it looks premium". Displacement reads as material under pressure. Flow fields read as current. Dithering reads as print and limited palette. Chrome reads as metal. Particles read as quantity. If the answer is only "movement", cut it.
2. What is on screen at frame 0, with no input? Law 3 of the doctrine. Pointer-driven effects are invisible in the state most visitors see. Pick one: seed it on mount along a designed path, give it autonomous idle motion, or accept it is a reward for interaction and make the composition complete without it.
3. Is it bounded or full-bleed? Full-bleed forces the effect quiet enough not to fight text, which is how it ends up reading as a filter someone left on. A bounded region running at full strength reads as intent. Prefer the panel, the masked band, the single figure.

The floor

Every one of these is a build check, not an intention.

Browsers cap live WebGL contexts at roughly 16. A leak does not error, it silently makes every later canvas fail. That is why teardown is on this list and not in a nice-to-have section.

Non-negotiable code shape

The self-stopping RAF machine

A loop that runs forever is a bug, not a default. It must stop when nothing is changing.

INCORRECT   const loop = () => { draw(); requestAnimationFrame(loop) }; loop()
CORRECT     idempotent start(), a `running` flag, stop() when settled or offscreen,
            lastTime reset on resume so there is no catch-up jump, delta clamped to 1/30,
            snap-to-target when within epsilon, and a `wake` closure the input handler calls.

Clamping delta matters: a backgrounded tab returns with a multi-second delta and an unclamped simulation explodes on the first frame back.

DPR sizing, done once

const dpr = Math.min(window.devicePixelRatio || 1, 2);   // never unclamped
const w = Math.round(rect.width * dpr), h = Math.round(rect.height * dpr);
if (canvas.width !== w || canvas.height !== h) { canvas.width = w; canvas.height = h; }

The guard is not a micro-optimization: writing canvas.width at all clears the drawing buffer and resets GL state, so an unguarded write inside a resize handler produces a flicker on every scrollbar appearance.

Options authored in CSS pixels get multiplied by DPR only at the uniform boundary, never at author time. Otherwise the effect changes size between a laptop and a phone.

Cleanup that actually releases

cancelAnimationFrame  ->  deleteTexture x N  ->  deleteFramebuffer x N
->  deleteProgram / deleteShader  ->  deleteBuffer  ->  observer.disconnect()
->  removeEventListener  ->  null the refs

React: this is the effect's return function, and it must run on every dependency change, not only unmount.

Reduced motion is a kill switch, not a slowdown

Four valid strategies, pick per effect and say which: snap easing factors to 1, kill the timeline and render the target state, refuse pointer input but keep the render, or pass a reduced uniform the shader branches on.

Freeze the clock at a time value you chose by looking at it. t = 0 is usually the least composed frame the effect ever has.

The fallback is the content, not a placeholder

INCORRECT   canvas fails -> show a static gradient image
CORRECT     the DOM content was never inside the canvas. The canvas is an overlay that
            is `aria-hidden` and `pointer-events: none`. Deleting it changes nothing
            about what the page says or what a visitor can do.

Test by deleting the element, never by trusting a fallback branch.

html-in-canvas (drawElement)

The @canvas-ui family hosts real DOM inside <canvas layoutsubtree>, captures it with ctx.drawElementImage(content, 0, 0) on onpaint, uses that as a GL texture, and shades it through a pointer-events: none output canvas. Text stays selectable and links stay clickable.

Two facts that decide whether you can use it:

• It needs Chrome or Edge 140+ with chrome://flags/#canvas-draw-element, or a production origin trial token. Everywhere else it falls back to a WebGL overlay over ordinary DOM.
• Feature detection must be SSR-safe or it hydration-mismatches. The correct shape: useSyncExternalStore(emptySubscribe, supportsHtmlInCanvas, () => false). The server snapshot returns false.

Design for the fallback, treat the native path as the upgrade. The reverse ships a site that looks unfinished to almost everyone.

Drag-driven effects fight the DOM: when content is real DOM, a drag is a text selection. Drive from pointermove with no button held, or set user-select: none and only on text nobody would copy.

Where the effect goes, per mode

One heavy component per page. Two fluid sims on one route is not twice as impressive, it is a dropped frame budget and a hot phone.

Never put a lens, refraction, or displacement effect over a form field. The control has to be legible while it is being used.

Effect vocabulary, mapped to meaning

Reach past transform and opacity. Each of these communicates something specific:

Pick the one whose meaning matches the brief. If two are equally apt, take the cheaper one.

Checks before this skill is done

• Every row of the floor table verified on the built page, not assumed
• The frame-0 question answered explicitly, and the answer is visible in the composition
• destroy() exists, is called, and 20 route changes do not grow the context count
• Canvas deleted in devtools: the page still says everything and does everything
• Reduced motion produces a still frame that was chosen by looking at it
• One heavy effect on the route, not two
• The effect's meaning matches the brief, and you can say what it is in one sentence