kuinetic 0.1.4 → 0.2.0

package/dist/types/advanced/shaders.d.ts

@@ -0,0 +1,972 @@
+/**
+ * kUInetic Shaders - Shared WebGL2 Shader System
+ */
+import type { EffectInstance, EffectParams, PrepareContext, Preset, Primitive } from '../core/types.js';
+import type { Registry } from '../core/registry.js';
+import type { Animator } from '../core/animator.js';
+import { type AdvancedEnv, type AnyWindow, type AnyDocument, type RafFunction, type CafFunction } from './base.js';
+import { type ProgramLocations } from './gl-utils.js';
+import { type AudioBand } from './audio.js';
+/**
+ * `gl-utils.ts`'s location set plus the one uniform only this module's programs declare.
+ *
+ * Kept here rather than in `ProgramLocations` because `u_audio` is a `glsl.ts` uniform and this
+ * file is the only thing that uploads it; every field is optional there, so a plain
+ * `ProgramLocations` (an older cached program, or a caller that built one itself) still satisfies
+ * this type and simply has no audio location to upload to.
+ */
+export type ShaderProgramLocations = ProgramLocations & {
+    u_audio?: WebGLUniformLocation | null;
+    u_noise?: WebGLUniformLocation | null;
+};
+export interface ShaderUniformOptions {
+    time?: number;
+    speed?: number;
+    strength?: number;
+    frequency?: number;
+    chromatic?: number;
+    iridescence?: number;
+    progress?: number;
+    /** One audio band's current value (0..1), or 0/absent for "no audio". */
+    audio?: number;
+    localMouse?: {
+        x: number;
+        y: number;
+    };
+    tintRgba?: [number, number, number, number];
+    blendMode?: number;
+    isDuotone?: boolean;
+    c1Rgba?: [number, number, number, number];
+    c2Rgba?: [number, number, number, number];
+    uvOrigin?: [number, number];
+    uvScale?: [number, number];
+    /** Border-box centre and half-extents in device px, y up from the canvas bottom. */
+    maskBox?: [number, number, number, number];
+    /** Corner radii in device px, TL, TR, BR, BL. */
+    maskRx?: [number, number, number, number];
+    maskRy?: [number, number, number, number];
+    /** What the ancestors' own opacity leaves this element painted at. */
+    maskAlpha?: number;
+    seed?: number;
+    scale?: number;
+    warp?: number;
+    /**
+     * How much of `fluid`/`liquid`/`particles`/`morph`'s trig stand-in is replaced by real noise.
+     *
+     * Zero in the six programs that do not declare it, and zero by default in the four that do, which
+     * is what keeps every page already running these modes rendering exactly what it rendered before.
+     */
+    noise?: number;
+    grain?: number;
+    /** Hue rotation in **radians**. The parameter is authored as an angle; `readAngleRadians` converts. */
+    hue?: number;
+    detail?: number;
+    bands?: number;
+    /** How many of `color1`..`color5` the author actually set. Below 2 the palette falls back. */
+    colorCount?: number;
+    /** The five palette stops, flattened to 20 floats for one `uniform4fv`. */
+    palette?: Float32Array;
+    /**
+     * Which stencil `mode: logo` cuts the field with — 0 none, 1 alpha, 2 luma, 3 inverted luma.
+     *
+     * See {@link MASK_MODES} and `glyphMask()` in `glsl.ts`. `0` in every mode but `logo`.
+     */
+    maskMode?: number;
+    /**
+     * Which pointer gestures the generative field responds to, as bits — see {@link HOVER_MODES}.
+     *
+     * The pointer position itself already arrives as {@link localMouse}, which every program that
+     * declares `u_mouse` has been receiving all along; this is only the switch that decides whether
+     * `GRADIENT_FS` reads it. `0` — the default — is the one value under which the pointer cannot
+     * reach a pixel at all.
+     */
+    hover?: number;
+    /** The colour the generative field is composited over, straight RGBA. Alpha `0` is "unset". */
+    backdropRgba?: [number, number, number, number];
+    /** The field's orientation in **radians**. Authored as an angle; `parseAngleRadians` converts. */
+    angle?: number;
+    /** How the generative field moves — see {@link MOTION_MODES}. `0` (`evolve`) is the default. */
+    motion?: number;
+}
+export interface ShaderDrawOptions extends ShaderUniformOptions {
+    mode: string;
+    strength: number;
+    speed: number;
+    frequency: number;
+    chromatic: number;
+    iridescence: number;
+    tintRgba: [number, number, number, number];
+    isDuotone: boolean;
+    c1Rgba: [number, number, number, number];
+    c2Rgba: [number, number, number, number];
+    blendMode: number;
+    texture?: WebGLTexture | null;
+    to?: string;
+    toTexture?: WebGLTexture | null;
+    /**
+     * Which `audio-source` band this instance follows, or `null` for none.
+     *
+     * The authored choice, not a value: the value is read per frame off the element (see
+     * `readAudioBand`) and arrives at the draw as {@link ShaderUniformOptions.audio}.
+     */
+    audioBand?: AudioBand | null;
+    /**
+     * Whether this instance follows `--kui-progress`, the property the scroll primitives publish.
+     *
+     * The authored choice, not a value — the same shape as {@link audioBand} and for the same
+     * reason: the value is read per frame off the element (see `readElementProgress`) and arrives
+     * at the draw as {@link ShaderUniformOptions.progress}.
+     */
+    scrubsFromScroll?: boolean;
+    /**
+     * This element's already-measured box, or absent to measure it here.
+     *
+     * The render loop measures every registered instance in its read pass and passes the answer down
+     * (see `renderFrame`); measuring inside the draw would interleave `getComputedStyle` and
+     * `getBoundingClientRect` with the previous instance's `opacity` write and force a style
+     * recalculation per element per frame.
+     */
+    geometry?: ElementGeometry | null;
+}
+export type ShaderProgramEntry = ProgramLocations | WebGLProgram | null | undefined;
+export interface ShaderRendererLike {
+    gl: WebGLRenderingContext | WebGL2RenderingContext | null;
+    canvas: HTMLCanvasElement | null;
+    window?: AnyWindow;
+    mouse: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Whether `mouse` has ever been written by a real pointer event.
+     *
+     * `false` means it has not, and {@link computeMousePos} answers the element's centre instead of
+     * believing the initial `{0, 0}`. `undefined` — a caller that does not model this at all — is
+     * taken as "trust `mouse`", so nothing outside this module changes.
+     */
+    hasPointer?: boolean;
+    quadBuffer: WebGLBuffer | null;
+    programs: Record<string, ShaderProgramEntry>;
+}
+/**
+ * Where a colour parse gets its canvas from — the injected adapter, not a global.
+ *
+ * Structurally `ResolvedEnv['createCanvas']`, named here because that is the *only* part of the
+ * environment the parser wants: everything above this line (hex, `rgb()`, {@link NAMED_COLORS}) is
+ * pure string work that must stay callable with no browser at all.
+ */
+export type ColorCanvasFactory = () => HTMLCanvasElement | null;
+/**
+ * An authored colour as premultiplied-free RGBA in 0..1.
+ *
+ * Hex, `rgb()`/`rgba()` and the small {@link NAMED_COLORS} table are parsed here. Anything else —
+ * `hsl()`, `oklch()`, `rebeccapurple`, a `color-mix()` — is handed to a 1x1 canvas, which is the
+ * browser's own parser and the only complete one.
+ *
+ * @param str - The authored value. Empty or unset answers opaque white, the harmless fallback for
+ *   an unset `color1`; `backdrop` reads the raw string first precisely because white is *not*
+ *   harmless there.
+ * @param createCanvas - Where the fallback canvas comes from. Defaults to the ambient document's,
+ *   resolved through `resolveEnv` rather than off a bare global, so a host with no document
+ *   answers `null` instead of throwing a `ReferenceError` into the `catch` above — which is what
+ *   reading `document` directly did, and it made the result silently environment-dependent.
+ *   `prepareShaders` passes its own resolved env, so an injected canvas always wins.
+ * @complexity O(n) in string length, plus one cached context construction per canvas source.
+ */
+export declare function parseColor(str?: string, createCanvas?: ColorCanvasFactory): [number, number, number, number];
+/**
+ * An authored `angle` parameter as radians, for a consumer that is GLSL rather than a stylesheet.
+ *
+ * `core/params.ts` normalises a bare `hue:30` to `30deg` but leaves an explicitly-united value
+ * alone, so all four CSS angle units can arrive here. Parsed rather than fed through `params.num`,
+ * which is documented as "bare number, or a percentage" and would answer the fallback for every
+ * spelling an angle parameter actually accepts.
+ *
+ * @param raw - The validated parameter string, e.g. `"30deg"`, `"0.5turn"`.
+ * @returns The angle in radians, or `0` for anything unparseable.
+ * @complexity O(n) in string length.
+ */
+export declare function parseAngleRadians(raw: string | undefined): number;
+/** How many palette stops the generative program's `u_colors` array holds. */
+export declare const PALETTE_SIZE = 5;
+/**
+ * The five palette stops as one flat `Float32Array`, plus how many are real.
+ *
+ * `colorCount` drives the ramp's segment count in GLSL, so the unset tail of the array is never
+ * read — it is filled with the last real stop anyway rather than left at zero, because a driver
+ * that clamps an index differently than expected should land on a colour that exists rather than
+ * on black.
+ *
+ * @param authored - The five parameter strings in order, empty for unset.
+ * @param createCanvas - Passed straight through to {@link parseColor}; see the note there.
+ * @returns The flattened palette and the number of stops the ramp should span.
+ * @complexity O(1) — the array is a fixed five entries.
+ */
+export declare function buildPalette(authored: string[], createCanvas?: ColorCanvasFactory): {
+    palette: Float32Array;
+    colorCount: number;
+};
+export declare const BLEND_MODES: {
+    normal: number;
+    screen: number;
+    multiply: number;
+    add: number;
+};
+export type ProgramOrLocations = ShaderProgramLocations | WebGLProgram | null;
+export declare function uploadUniforms(gl: WebGLRenderingContext | WebGL2RenderingContext, progInfo: ProgramOrLocations, opt: ShaderUniformOptions): void;
+export declare function uploadColorUniforms(gl: WebGLRenderingContext | WebGL2RenderingContext, progInfo: ProgramOrLocations, opt: ShaderUniformOptions): void;
+/** An axis-aligned box in viewport-relative CSS pixels. */
+export interface Inset {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface ElementGeometry {
+    /** Border box. What the corner mask is measured against. */
+    border: Inset;
+    /** Where the replaced content would be painted if nothing clipped it. */
+    paint: Inset;
+    /** Content box narrowed by every clipping ancestor. */
+    clip: Inset;
+    /** Border-box corner radii, `[x, y]` per corner in TL, TR, BR, BL order. */
+    radii: [number, number, number, number, number, number, number, number];
+    /**
+     * What the replica has to be painted at: the ancestors' opacities multiplied together, and the
+     * element's own on top of them.
+     *
+     * The host's own used to be left out, on the reasoning that `opacity` is this module's to write —
+     * but that confuses the property with the author's value for it. A `.hero { opacity: .25 }`
+     * carrying a shader had its original hidden by `hideBehindRenderer` and its replica drawn at 1,
+     * so the one element on the page that was meant to be a quarter visible was the only one at full
+     * strength. See {@link hostAlpha} for how the author's value survives being overwritten.
+     */
+    alpha: number;
+    /**
+     * The host's own opacity alone, already folded into {@link alpha}.
+     *
+     * Handed back so a caller can cache it. `hideBehindRenderer` writes `opacity: 0` on the very
+     * element this is measured from, so from the second frame onwards a live read answers 0 — fold
+     * that in and the replica vanishes, which leaves the host hidden behind nothing at all. The
+     * instance therefore keeps the last value read while the element was still visible and passes it
+     * back in; see `measureElementGeometry`'s `hostAlpha` parameter.
+     */
+    hostAlpha?: number;
+}
+/**
+ * Everything about one element's box the draw has to reproduce, in CSS pixels.
+ *
+ * Pure reads, no GL and no canvas: the device-pixel conversion needs the canvas dimensions and
+ * happens later, in {@link resolveDrawBox}, so that a caller can measure once per frame in the
+ * read pass and draw from the cached answer.
+ *
+ * @param el - The element the shader stands in for.
+ * @param win - The window whose `innerHeight`/`devicePixelRatio`/`getComputedStyle` to use.
+ * @param fullBox - Paint to the border box instead of the content box. What a *generated* image
+ *   wants: it is a background, and backgrounds paint to the border box, so measuring the content
+ *   box would inset the field by the element's border and padding while `radiiOf` keeps measuring
+ *   the corner mask against the border box — visibly mismatched corners on any padded host.
+ *   The replaced-content path (every image filter) must keep the content box, because that is the
+ *   box `object-fit` resolves against.
+ * @param hostAlpha - The element's own opacity, for a caller that already hid it. Omitted means
+ *   "read it live", which is right up to the first `hideBehindRenderer` and right forever for a
+ *   generative mode, which never hides its host. After that the live value is this module's own
+ *   `0` and the author's has to be supplied from the caller's cache.
+ * @returns Its geometry, or `null` when it is not on screen at all.
+ * @complexity O(d) in ancestor depth, capped at {@link ANCESTOR_WALK_LIMIT}.
+ */
+export declare function measureElementGeometry(el: HTMLElement, win?: AnyWindow, fullBox?: boolean, hostAlpha?: number): ElementGeometry | null;
+export interface ScissorResult {
+    rect: DOMRect;
+    uvOrigin: [number, number];
+    uvScale: [number, number];
+    /** Border-box centre and half-extents in device px, y measured up from the canvas bottom. */
+    maskBox: [number, number, number, number];
+    /** Corner x-radii in device px, TL, TR, BR, BL — matching `maskRy`. */
+    maskRx: [number, number, number, number];
+    maskRy: [number, number, number, number];
+    alpha: number;
+}
+/**
+ * Turn one element's CSS-pixel geometry into a scissor rect and the UV window over its texture.
+ *
+ * The UV window is what makes `object-fit` work: the quad only ever covers the part of the painted
+ * box that survives clipping, and `uvOrigin`/`uvScale` say which part of the *image* that is. A
+ * `cover` hero therefore samples the same crop CSS shows, and a half-off-screen element samples
+ * its visible half, through one mechanism rather than two.
+ *
+ * @returns `null` when nothing of the element is left to draw.
+ * @complexity O(1).
+ */
+export declare function resolveDrawBox(geom: ElementGeometry, canvas: HTMLCanvasElement, dpr: number): (ScissorResult & {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+}) | null;
+/**
+ * Measure `el`, point the viewport and scissor box at it, and hand back its UV window.
+ *
+ * Kept as one call for the unit suites and for any caller that has no cached geometry; the render
+ * loop measures in its read pass instead and passes the result in as
+ * {@link ShaderDrawOptions.geometry}.
+ */
+export declare function setupScissor(gl: WebGLRenderingContext | WebGL2RenderingContext, el: HTMLElement, canvas: HTMLCanvasElement, win?: AnyWindow): ScissorResult | null;
+export declare function bindShaderTexture(gl: WebGLRenderingContext | WebGL2RenderingContext, progInfo: ProgramOrLocations, texture: WebGLTexture | null | undefined, toTexture?: WebGLTexture | null | undefined): void;
+export declare function drawElementQuad(renderer: ShaderRendererLike, el: HTMLElement, opt?: Partial<ShaderDrawOptions>): boolean;
+export type ShaderParamAccessor = EffectParams | {
+    keyword?: (name: string) => string;
+    text: (name: string, fallback?: string) => string;
+    num: (name: string, fallback?: number) => number;
+};
+/**
+ * Modes that generate their image from mathematics rather than sampling a source.
+ *
+ * Three behaviours key off this set, and each one is a place the filter assumption is baked in:
+ *
+ * 1. **The texture requirement.** `drawCall`'s `drew = !!texture && …` is the single line that made
+ *    every mode a filter — no loaded `<img>`, no draw. A generator has no source to wait for.
+ * 2. **Hiding the host.** A filter stands in for the element it replaces, so hiding it is right. A
+ *    generator is drawn over an element the author may have put content in, so hiding it would
+ *    destroy that content to no purpose.
+ * 3. **The quad's box.** A generator is a background, and backgrounds paint to the border box; the
+ *    replaced-content path measures the content box, which insets by border and padding while the
+ *    corner mask still measures the border box.
+ */
+export declare const GENERATIVE_MODES: Set<string>;
+/**
+ * Every mode the `mode:` keyword accepts, in one list.
+ *
+ * The single source for `SHADER_PARAMETERS.mode.keywords` *and* for `prepareShaders`' gate; they
+ * were two literals before, which is one edit away from a keyword the gate rejects.
+ *
+ * `logo` is deliberately **not** in {@link GENERATIVE_MODES}. It generates its colour, but it
+ * behaves in every other respect exactly like the five filters: its texture is required (the
+ * image is the stencil), its host is hidden (the field replaces it), and it measures the content
+ * box so `object-fit` resolves the way it does for `displace`. That is what made it the mode that
+ * needed no structural change to ship.
+ */
+export declare const SHADER_MODES: readonly ["displace", "fluid", "liquid", "particles", "morph", "gradient", "logo"];
+/**
+ * `mask:` as the `u_maskMode` the generative program branches on. See `glyphMask()` in `glsl.ts`.
+ *
+ * `gradient` is pinned to `0` whatever the author wrote: there is no texture bound in that mode,
+ * so a stencil is not a thing it can have, and silently honouring `mask:` there would produce a
+ * black rectangle rather than a warning.
+ */
+export declare const MASK_MODES: Record<string, number>;
+/**
+ * `hover:` as the bitfield `u_hover` tests — `both` is `stir | light` and not a third code path.
+ *
+ * Bits rather than four ordinals because the shader's two gestures act at different stages (one on
+ * the sample coordinate, one on the colour that coordinate produced), so `both` is genuinely the
+ * two of them and there is nothing for a third branch to say.
+ */
+export declare const HOVER_MODES: Record<string, number>;
+/**
+ * `motion:` as the int `u_motion` branches on.
+ *
+ * `evolve` is `0` and is the default, because it is what this program has always done: time as the
+ * noise field's third axis, the pattern changing in place. `drift` and `swirl` are additions on
+ * top of it. See {@link SHADER_PARAMETERS.motion} for why the inert keyword had to exist.
+ */
+export declare const MOTION_MODES: Record<string, number>;
+/**
+ * @param params - The authored parameters.
+ * @param createCanvas - The env's canvas source, threaded to every colour parse below. Optional
+ *   because a caller holding nothing but an accessor is a supported shape, and the colours it
+ *   authored are overwhelmingly hex; `prepareShaders` resolves its env first and passes it, so the
+ *   one path that reaches a real page never falls back.
+ */
+export declare function extractShaderOptions(params: ShaderParamAccessor, createCanvas?: ColorCanvasFactory): ShaderDrawOptions;
+/**
+ * This element's scroll/scrub progress, or -1 when nothing has declared one.
+ *
+ * **Only called for an instance that authored `scrub: scroll`** — see `readInputs`. Reading it
+ * unasked is what the parameter exists to stop: the fallback below means an *ancestor's*
+ * `scroll-progress` reaches this element, and at the top of a scroll range that value is `0`,
+ * which every program treats as "no effect". A shader anywhere inside a scrollytelling section
+ * therefore rendered a pixel-faithful copy of its own source and looked dead, with no way to say
+ * no. The `audio:` parameter twelve lines below the schema entry had already been written against
+ * exactly this failure; the scroll channel simply never got the same gate.
+ *
+ * Checks the element's own inline style first — the fast path, and the only one that mattered
+ * while a shader element could only ever read a scroll-mechanics primitive on itself. Falling back
+ * to `getComputedStyle` is what makes an *ancestor's* primitive reach it too: `--kui-progress` is
+ * an ordinary, unregistered custom property (nothing in this codebase declares it with
+ * `@property`), so it inherits down the DOM tree by default — a `scroll-progress` element three
+ * levels up is already visible to `getComputedStyle` on this element without this module doing
+ * anything special, once something here actually asks.
+ *
+ * Callers must not call this once per element as each one draws; see `SharedShaderRenderer`'s
+ * `progressReaders` pass, which reads every registered instance's progress before any instance's
+ * draw call runs and can write a style. Reading and writing style in the same pass across several
+ * elements would force a style recalculation per element instead of at most once per frame.
+ *
+ * @complexity O(1) time (one inline read, at most one computed-style read); O(1) space.
+ */
+export declare function readElementProgress(el: HTMLElement): number;
+/**
+ * Where the shared canvas sits in the page's stacking order when the author says nothing.
+ *
+ * **Deliberately low.** This was `9999` and the defence written for it — that anything lower hides
+ * the replica behind a positioned card — does not survive examination: a positioned card that
+ * overlaps a shader element probably *should* paint on top, which is stacking working rather than
+ * stacking broken. What `9999` actually bought was the shared canvas painting over the page's own
+ * modals, sticky headers and toasts, which is unambiguously wrong and is the bug that was filed.
+ *
+ * `1` rather than `0` or `auto` so the canvas still sits above the page's ordinary static content,
+ * which is the one thing it does have to do.
+ */
+export declare const DEFAULT_SHADER_Z_INDEX = 1;
+/** The custom property an author sets to move the shared canvas. See {@link readShaderZIndex}. */
+export declare const SHADER_Z_PROPERTY = "--kui-shader-z";
+/**
+ * The author's stacking order for the shared canvas, or {@link DEFAULT_SHADER_Z_INDEX}.
+ *
+ * ```css
+ * :root { --kui-shader-z: 500; }
+ * ```
+ *
+ * One line in the page's own stylesheet, no JS and no build step — custom properties inherit, so a
+ * value on `:root` reaches a canvas this module created even though no stylesheet can name it.
+ *
+ * **Why not a `data-kui` parameter.** `SharedShaderRenderer` keeps *one* canvas for the whole page.
+ * A per-element `zIndex:` would look per-element and silently not be — two shader elements asking
+ * for different values, last writer wins, and the loser has no way to tell. That is the "one key,
+ * two meanings" failure `core/types.ts` already documents. A page-level object gets a page-level
+ * knob.
+ *
+ * **This does not close the architectural ceiling.** Moving the number lets *one page cope*; it
+ * still does not let a shader sit *behind* content in any general way. There is one canvas, so the
+ * value moves every replica on the page at once, and whatever is positioned above the new number
+ * now covers the shaders instead. A shader that genuinely composes with the content over it needs
+ * per-element canvases, which is a decision that has not been made. See `docs/advanced-modules.md`.
+ *
+ * Read the same shape as `readElementProgress`: inline first, computed as the fallback, so a value
+ * set in a stylesheet reaches it. Anything that is not a finite number — `auto`, a `var()` that
+ * resolved to nothing, junk — falls back to the default rather than writing a broken `z-index`.
+ *
+ * @complexity O(1): one inline read and at most one computed-style read, once per canvas.
+ */
+export declare function readShaderZIndex(doc: AnyDocument, win: AnyWindow): number;
+export type ShaderDrawFn = (gl: WebGLRenderingContext | WebGL2RenderingContext, timeSeconds: number) => void;
+/**
+ * Singleton WebGL2 Renderer.
+ */
+export declare class SharedShaderRenderer {
+    env: AdvancedEnv;
+    window: AnyWindow;
+    document: AnyDocument;
+    createCanvas: () => HTMLCanvasElement | null;
+    raf: RafFunction;
+    caf: CafFunction;
+    canvas: HTMLCanvasElement | null;
+    gl: WebGLRenderingContext | WebGL2RenderingContext | null;
+    quadBuffer: WebGLBuffer | null;
+    rafId: number | null;
+    drawCalls: Map<string, ShaderDrawFn>;
+    contextCallbacks: Map<string, {
+        onLost: () => void;
+        onRestored: () => void;
+    }>;
+    /**
+     * One style-reading pass per registered instance — scroll progress and, when the author asked
+     * for one, an audio band — run in full before any instance's draw call this frame. See
+     * `renderFrame` for why the ordering, not just the reads themselves, is the point.
+     */
+    inputReaders: Map<string, () => void>;
+    programs: Record<string, ShaderProgramLocations | null>;
+    refCount: number;
+    mouse: {
+        x: number;
+        y: number;
+    };
+    /** Cleared until a real `pointermove` lands. See {@link computeMousePos}. */
+    hasPointer: boolean;
+    isContextLost: boolean;
+    /**
+     * Bumped every time this renderer's GL objects stop being valid, i.e. on each context loss.
+     *
+     * It exists because "is this handle still real?" has no other answer. A `WebGLTexture` from a lost
+     * context is an ordinary live JavaScript object — binding it raises `INVALID_OPERATION` and
+     * samples nothing, and neither the draw nor `drawElementQuad`'s return value can tell.
+     *
+     * The hole it closes: `cancel()`/`finish()` unregister an instance, which takes its entry out of
+     * `contextCallbacks` with it, so an *inactive* instance is never told the context went away. Its
+     * texture holders kept answering with pre-loss handles, and `acquireRenderer` short-circuits on
+     * re-activation because the renderer itself was never destroyed — so a hover, a hover-out, a
+     * context loss and a second hover drew a blank replica over a hidden image, permanently.
+     *
+     * Stamping the holders rather than keeping every acquired instance registered for context events:
+     * the stamp is checked where the stale handle is actually read, so it holds however the instance
+     * came to miss the event, and it costs two compares per holder per frame. See
+     * {@link initTextureHolder}.
+     */
+    contextGeneration: number;
+    mapKey: object;
+    onPointer?: (e: PointerEvent | {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    onContextLost?: (e: Event) => void;
+    onContextRestored?: () => void;
+    constructor(env?: AdvancedEnv);
+    /**
+     * Whether `destroy()` has run. A destroyed renderer never comes back to life.
+     *
+     * `destroy()` un-maps itself, so the object an already-prepared instance is still holding is no
+     * longer the one `getSharedShaderRenderer` hands out. Letting `acquire()` re-`init()` that object
+     * therefore built a *second* full-viewport canvas and WebGL2 context in one document — and then
+     * a third, because the next element to be prepared found nothing in the map and made its own,
+     * and whichever of them tore down next deleted the shared document key from under the live one.
+     * Cycling shader elements on an SPA route walked straight into the browser's 8-16 context cap.
+     *
+     * So a teardown is final, and `RendererRef` is what gets an orphaned instance back onto the live
+     * renderer.
+     */
+    isDestroyed: boolean;
+    acquire(): boolean;
+    release(): void;
+    init(): boolean;
+    /**
+     * Undo a half-built `init()` and report it as a failure.
+     *
+     * Not `destroy()`: nothing has acquired this renderer yet, so there is no teardown to broadcast,
+     * and marking it `isDestroyed` would retire an object that is free to try again the next time
+     * something acquires it. Under transient memory pressure that retry is the whole point — the
+     * alternative is a permanently dead renderer for a `createBuffer` that would succeed a second
+     * later. The canvas goes because it is already in the document by this point; leaving it would
+     * stack one invisible full-viewport canvas per attempt.
+     */
+    private abandonInit;
+    /**
+     * Allocate and fill the one static buffer every draw in this module reads its vertices from.
+     *
+     * Returns whether it worked, and the caller has to care. `gl.createBuffer()` returns `null` under
+     * memory pressure rather than throwing, and so does nothing else downstream: `vertexAttribPointer`
+     * and `drawArrays` against a null binding only *set* a GL error, and `drawElementQuad` used to
+     * return `true` regardless. The visible result was the worst possible one — every affected
+     * element's `opacity` driven to 0 by `hideBehindRenderer` with nothing drawn over it, so the page
+     * lost its images rather than losing an effect. A renderer that cannot allocate this is not a
+     * renderer, so it fails here instead.
+     *
+     * `bufferData` is guarded too, and only for a host that throws rather than raising `OUT_OF_MEMORY`
+     * through the error queue. Reading the queue is deliberately not done: `getError` is a
+     * synchronous round-trip to the GPU process, and the allocation failure it would catch is already
+     * caught by the null above.
+     */
+    initQuad(): boolean;
+    initPrograms(): void;
+    bindEvents(): void;
+    createTexture(source: TexImageSource): WebGLTexture | null;
+    register(id: string, fn: ShaderDrawFn, callbacks?: {
+        onLost: () => void;
+        onRestored: () => void;
+    }, readInputs?: () => void): void;
+    unregister(id: string): void;
+    startLoop(): void;
+    stopLoop(): void;
+    renderFrame(timeSeconds: number): void;
+    /**
+     * Every registered instance's draw, in registration order, each one isolated from its neighbours.
+     *
+     * The snapshot is here because a draw call may unregister itself — the `catch` below does — and
+     * mutating `drawCalls` under a live iterator would skip its neighbour. But a snapshot of the
+     * *entries* must not become a snapshot of the *context*, which is why the `gl` is re-read per
+     * iteration rather than taken from `renderFrame`'s. `destroy()` nulls `gl` and deletes the
+     * programs, so a draw call that dropped the last reference mid-frame left every remaining entry
+     * in the snapshot drawing through a disposed context, on a renderer already `isDestroyed` with
+     * its `drawCalls` cleared. The same re-read covers a context lost mid-frame, where `gl` survives
+     * but the programs and buffers do not.
+     *
+     * @param timeSeconds - This frame's timestamp, passed to every draw call.
+     * @complexity O(n) in registered instances.
+     */
+    private runDrawCalls;
+    destroy(): void;
+}
+export declare function getSharedShaderRenderer(env?: AdvancedEnv): SharedShaderRenderer;
+/**
+ * The live shared renderer for one document, across a teardown.
+ *
+ * `prepareShaders` runs during the animator's scan while `activate()` can be much later — a
+ * below-the-fold `on:enter` element is prepared on load and activated on scroll — so the renderer
+ * an instance was handed at prepare time can be destroyed before it is ever used. This re-resolves
+ * instead of reviving: `getSharedShaderRenderer` builds a fresh renderer, the map keeps pointing at
+ * the live one, and the document still has exactly one canvas and one context.
+ */
+export interface RendererRef {
+    get(): SharedShaderRenderer;
+}
+export declare function createRendererRef(env?: AdvancedEnv): RendererRef;
+/**
+ * Install (or clear) the renderer for one document.
+ *
+ * A renderer's `destroy()` removes exactly one map entry: the key it was built for. Storing an
+ * instance under some *other* document's key therefore made the two halves asymmetric — destroy
+ * cleaned up document A, and document B was left holding a renderer whose canvas had been removed
+ * and whose GL resources were gone, handed out to every later `getSharedShaderRenderer` for B.
+ *
+ * So the instance's own key wins, and a mismatched caller key is cleared rather than pointed at
+ * another document's renderer: whatever is reachable from the map is always reachable from the
+ * key its own teardown will delete.
+ */
+export declare function setSharedShaderRenderer(instance: SharedShaderRenderer | null, env?: AdvancedEnv): void;
+export declare function prepareShaders(el: Element, params: EffectParams, ctx?: PrepareContext | null): EffectInstance;
+export declare const SHADER_PARAMETERS: {
+    mode: {
+        type: "keyword";
+        default: string;
+        keywords: ("morph" | "displace" | "gradient" | "fluid" | "liquid" | "particles" | "logo")[];
+        cssProperty: string;
+    };
+    strength: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    speed: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    frequency: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    chromatic: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    /**
+     * How far the colour ramp is wrapped back on itself — the shimmer count.
+     *
+     * Ranged 0..8 rather than the 0..1 it carried before `mode: gradient` existed. The old bound was
+     * right for a mix amount and wrong for a wrap count, and it cost nothing to police because **no
+     * fragment program declared `u_iridescence` at all** — the value was extracted and uploaded to a
+     * location that was `null` in all five programs. It reaches a shader for the first time here.
+     */
+    iridescence: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    tint: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+    color1: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+    color2: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+    color3: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+    color4: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+    color5: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+    /** Which pattern. The same seed gives the same image on every load, which is the point of it. */
+    seed: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        integer: boolean;
+        cssProperty: string;
+    };
+    /** How zoomed the field is. Larger means smaller, more numerous shapes. */
+    scale: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    /**
+     * How many octaves of detail ride on the base shapes.
+     *
+     * Named `detail` rather than the reference tools' "definition" — the plainer word for the same
+     * idea. Capped at 6, which is `KUI_MAX_OCTAVES` in the shader; a seventh would be accepted here
+     * and silently ignored there.
+     */
+    detail: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        integer: boolean;
+        cssProperty: string;
+    };
+    /** How far a second field distorts the first. The difference between contour rings and liquid. */
+    warp: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    /**
+     * How much of `fluid`, `liquid`, `particles` and `morph`'s motion comes from real noise.
+     *
+     * Those four shipped with a single trigonometric term standing in for noise, which bands and
+     * repeats visibly. This crossfades that term into the same `kuiFbm` field `mode: gradient`
+     * generates from — `0` is the shipped picture exactly, `1` is the field on its own, and the
+     * values between are a genuine dial rather than a rounded switch.
+     *
+     * **It is off by default and must stay that way.** Four modes are already in use; turning this
+     * on for them without being asked would restyle live pages. See `FILTER_NOISE_GLSL` in
+     * `glsl.ts` for why it is a parameter of its own rather than `warp` doing double duty.
+     *
+     * Above `0` it is also what gives `seed`, `scale`, `warp` and `detail` a meaning on these four
+     * modes; below it they are read and uploaded but nothing samples them. `mode: displace`'s ripple
+     * is a deliberate radial wave rather than fake noise, and `gradient`/`logo` are already nothing
+     * but the noise core, so all three ignore this.
+     */
+    noise: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    /** Posterise the ramp into this many steps. `0` is off, as with `chromatic` and `iridescence`. */
+    bands: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        integer: boolean;
+        cssProperty: string;
+    };
+    /** Film grain amount. */
+    grain: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    /**
+     * Hue rotation, as a real angle (`hue: 30deg`, `hue: 0.25turn`).
+     *
+     * An `angle` rather than a normalised scalar, matching `carousel`'s `tilt:` and this repository's
+     * standing rejection of normalised ranges where a CSS unit exists. A bare `hue: 30` is accepted
+     * too — `core/params.ts` normalises it to `30deg`.
+     */
+    hue: {
+        type: "angle";
+        default: string;
+        cssProperty: string;
+    };
+    /**
+     * Which part of `mode: logo`'s host image is the mark. Ignored by every other mode.
+     *
+     * `alpha` for the usual transparent-ground SVG or PNG. `luma` and `luma-invert` are for a format
+     * that has no alpha to read — a JPEG under `alpha` gives an all-opaque stencil and fills the
+     * whole rectangle. `luma` takes the bright pixels as the mark, `luma-invert` the dark ones; both
+     * directions are spelled out because guessing produces a perfect negative of the mark, which
+     * looks deliberate and is exactly wrong.
+     */
+    mask: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+    /**
+     * How `mode: gradient` and `mode: logo` answer the pointer. Ignored by the five filter modes.
+     *
+     * Being *responsive to the pointer* is the one thing a shader background does that a video of a
+     * shader cannot, and these two modes — the two built to stand in for a video background — were
+     * the only ones in the tier with no pointer response at all. `displace` and `fluid` have read
+     * `u_mouse` since they were written.
+     *
+     * - `stir` — the cursor drags the colour flow around it, like stirring thick paint. It moves the
+     *   field's *sample point*, so on `mode: logo` the mark's edges do not move: `glyphMask()` reads
+     *   the host image at the undistorted coordinate and multiplies the finished colour, which means
+     *   the fill swirls inside a stencil that stays exactly where it was.
+     * - `light` — the cursor is a torch held over the surface. Nothing moves; the colour under the
+     *   pointer is multiplied up, which raises its saturation rather than washing it toward white.
+     * - `both` — the two together. They compose cleanly because they act at different stages, one on
+     *   the coordinate and one on the colour that coordinate produced.
+     *
+     * `none` by default, and `none` means the shader never reads `u_mouse` at all — not that it
+     * reads it and multiplies by zero. Every page already running these modes renders what it always
+     * rendered, byte for byte.
+     *
+     * With no pointer yet — the state of every page on load, every phone, and every screenshot —
+     * `computeMousePos` answers the element's centre, so `light` rests as a centred glow and `stir`
+     * as a centred swirl. Both are compositions someone might have authored on purpose, which is the
+     * bar a resting state has to clear.
+     */
+    hover: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+    /**
+     * A colour painted behind the generative field, inside the element's own shape.
+     *
+     * What it is for is `mode: logo`: outside the mark the field has no coverage, so this is the
+     * plate the mark sits on instead of the page showing through.
+     *
+     * On a bare `mode: gradient` it is **invisible**, and that is arithmetic rather than an
+     * oversight — the field is opaque, so there is nothing behind it to see. It becomes visible
+     * there through a `tint` whose alpha is below 1, which is how a field is made to sit *on* a page
+     * colour rather than replace it. Unset by default, and read through the raw parameter string
+     * rather than `parseColor`, whose empty-input fallback is opaque white.
+     */
+    backdrop: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+    /**
+     * The generative field's orientation: the axis it runs along.
+     *
+     * `transform: rotate()`'s convention — clockwise-positive, `0deg` pointing right — because that
+     * is the one an author already has. It turns the field's whole domain, so it is visible at the
+     * library defaults rather than only in company with another parameter, and it is the axis
+     * `motion: drift` travels along. One idea with two consequences, not two behaviours: the field
+     * has an axis, this names it, and `drift` slides along the thing it named.
+     *
+     * An `angle` rather than a normalised scalar, matching `hue` above and this repository's
+     * standing rejection of 0..1 ranges where a CSS unit exists. A bare `angle: 30` is accepted —
+     * `core/params.ts` normalises it to `30deg`.
+     */
+    angle: {
+        type: "angle";
+        default: string;
+        cssProperty: string;
+    };
+    /**
+     * How the generative field moves. Ignored by the five filter modes.
+     *
+     * - `evolve` — the field changes *in place*. Time is the noise function's third axis rather than
+     *   a translation of a 2D field, which is why it reads as the pattern genuinely evolving instead
+     *   of sliding past. See `NOISE_GLSL` in `glsl.ts`.
+     * - `drift` — it also travels along `angle`, at a rate proportional to `scale` so the visual
+     *   speed is the same at any zoom.
+     * - `swirl` — it also turns about the element's centre.
+     *
+     * **`evolve` exists so that the default can be inert.** `drift` would have been the natural
+     * default name, and it is what this parameter's brief asked for — but `drift` is a new look, and
+     * defaulting to it would restyle every page already running `gradient` or `logo` on the next
+     * release. That is the same trap `noise:` above is written around, and the reason `hover:`
+     * defaults to `none`. So the shipped behaviour keeps the default and gets an accurate name, and
+     * the two new ones are opt-in. `drift` and `swirl` add to `evolve` rather than replacing it, so
+     * a travelling field is still changing as it goes rather than one frozen picture towed across
+     * the box.
+     */
+    motion: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+    blend: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+    to: {
+        type: "text";
+        default: string;
+        cssProperty: string;
+    };
+    /**
+     * A fixed scrub position, 0..1. `-1` is the unauthored sentinel and means "no scrub".
+     *
+     * `--kui-shader-progress`, **not** `--kui-progress`. Every authored parameter reaches
+     * `element.style` as its custom property — `core/compile.ts`'s `buildPlan` runs `resolveParams`
+     * over JS-rendered entries too — so while this pointed at `--kui-progress` an authored
+     * `progress: 0.4` wrote the scroll primitives' own channel onto the element: it raced
+     * `scroll-progress` when the two were composed, and it inherited down to every descendant
+     * shader and pinned timeline underneath. `test/carousel-3d.test.ts` already carries a
+     * regression test that a primitive must not publish `--kui-progress` meaning something else.
+     * Nothing is lost by renaming — this module reads the authored value from the parameter, never
+     * back off the property.
+     */
+    progress: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    /**
+     * Whether this shader is scrubbed by `--kui-progress` — the property `scroll-progress`,
+     * `timeline: pin` and the rest of the scroll family publish.
+     *
+     * Opt-in, and `off` by default, for the same reason `audio:` below is: the value arrives as a
+     * custom property written by some *other* primitive, and `--kui-progress` is an ordinary
+     * inheriting custom property, so a shader that read one unasked changed its own output the
+     * moment an unrelated `scroll-progress` appeared anywhere above it in the tree. That was not a
+     * subtle drift — at the top of a scroll range the published value is `0`, every program
+     * multiplies its effect by it, and the shader rendered an untouched copy of the source image.
+     * Dead, silently, with no way for the author to decline.
+     *
+     * `keyword`, so the list is closed and a typo warns instead of quietly doing nothing.
+     * `--kui-shader-scrub` is a name read by this module's JavaScript and by no stylesheet, so
+     * setting the custom property directly does nothing; the value itself is read from
+     * `--kui-progress`, which is a different contract entirely.
+     */
+    scrub: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+    /**
+     * Which `audio-source` band drives this shader, if any.
+     *
+     * Opt-in, and `off` by default: the value arrives as a custom property written by some *other*
+     * primitive, so a shader that read one unasked would change its own output the moment an
+     * unrelated `audio-source` appeared anywhere above it in the tree.
+     *
+     * `keyword`, so the list is closed — and `--kui-shader-audio` is a name, read by this module's
+     * JavaScript and by no stylesheet, so setting the custom property in CSS does nothing. The
+     * band values themselves are read from `--kui-audio-*`, which is a different contract entirely
+     * (`audio.ts`'s `AUDIO_BAND_PROPERTIES`).
+     */
+    audio: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+};
+export declare const SHADERS_PRIMITIVE: Primitive;
+export declare const SHADERS_PRESETS: Preset[];
+export declare function registerShaders(target: unknown): Registry | Animator;