kuinetic 0.1.3 → 0.2.0

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

@@ -0,0 +1,233 @@
+/**
+ * Shared primitives and runtime utilities for kUInetic Advanced Modules.
+ */
+import type { EffectInstance, PrepareContext, Preset, Primitive } from '../core/types.js';
+import type { StyleLedger } from '../core/owned-styles.js';
+import type { Registry } from '../core/registry.js';
+import type { Animator } from '../core/animator.js';
+export interface WindowLike {
+    innerWidth?: number;
+    innerHeight?: number;
+    devicePixelRatio?: number;
+    performance?: {
+        now?: () => number;
+    };
+    addEventListener?: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void;
+    removeEventListener?: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions) => void;
+    requestAnimationFrame?: (fn: FrameRequestCallback) => number;
+    cancelAnimationFrame?: (id: number) => void;
+    getComputedStyle?: (el: Element) => CSSStyleDeclaration;
+}
+export interface DocumentLike {
+    body?: {
+        appendChild?: (node: unknown) => unknown;
+    } | null;
+    createElement?: (tagName: string) => unknown;
+}
+export type AnyWindow = Window | WindowLike | null;
+export type AnyDocument = Document | DocumentLike | null;
+export type RafFunction = (fn: FrameRequestCallback) => number | null;
+export type CafFunction = (id: number | null) => void | null;
+/**
+ * A wall-clock delay, and its cancel — the env's answer to "later, once".
+ *
+ * Separate from {@link RafFunction} because the two answer different questions: `raf` schedules the
+ * *next frame*, which is what a loop wants, while this schedules a fixed duration, which is what a
+ * grace period wants. A grace period counted in frames is a grace period that never elapses in a
+ * background tab — the one place where holding the resource costs the most.
+ *
+ * It is injectable for the same reason `raf` is: it is a timing decision the host can own, and a
+ * suite that cannot drive it either waits out the real duration or leaves the timer pending. Do
+ * *not* reach for `window.setTimeout` instead — {@link WindowLike} does not declare it, and the
+ * partial window doubles these suites inject would silently never fire.
+ *
+ * Named to match `defaultGestureDeps` in `core/gesture.ts`, which is the same pattern in core.
+ */
+export type SetTimerFunction = (fn: () => void, ms: number) => number | null;
+export type ClearTimerFunction = (id: number | null) => void;
+export interface AdvancedEnv {
+    window?: AnyWindow;
+    document?: AnyDocument;
+    createCanvas?: () => HTMLCanvasElement | null;
+    raf?: RafFunction;
+    caf?: CafFunction;
+    setTimer?: SetTimerFunction;
+    clearTimer?: ClearTimerFunction;
+}
+export interface ResolvedEnv {
+    window: AnyWindow;
+    document: AnyDocument;
+    createCanvas: () => HTMLCanvasElement | null;
+    raf: RafFunction;
+    caf: CafFunction;
+    setTimer: SetTimerFunction;
+    clearTimer: ClearTimerFunction;
+}
+export interface EffectInstanceOptions {
+    continuous?: boolean;
+    activate?: () => void;
+    cancel?: () => void;
+    finish?: () => void;
+    destroy?: () => void;
+}
+export declare function clamp(val: number, min: number, max: number): number;
+/**
+ * Anything that can hand back one element's inline-style ledger.
+ *
+ * Deliberately narrower than `LedgerSet`: core's set (`createLedgerSet`) and this directory's
+ * shared registry (`createAdvancedLedgers`) both satisfy it, so `styleOf` is one guard for both
+ * and a module can be moved from one to the other without touching a single write site.
+ */
+export interface ElementLedgers {
+    style(el: Element): StyleLedger;
+}
+/**
+ * This element's owned-write ledger, or `null` when the object cannot carry one.
+ *
+ * Every module here manages the author's inline styles through `core/owned-styles.ts` rather than
+ * a snapshot of its own, and the reason is timing: `style(el)` builds that element's ledger the
+ * first time it is *asked for*, and the ledger records a property's prior value the first time
+ * that property is *written*. Asking at the write site is therefore the same thing as "capture
+ * immediately before the first write", which is the invariant five rounds of review kept finding
+ * broken — a snapshot taken at construction or preparation, restored much later over an author
+ * value that had changed in between.
+ *
+ * The guard exists because `createStyleLedger` reads `hasAttribute('style')` the moment it is
+ * built, and these controllers are constructed directly rather than by the animator: `prepare`
+ * hands them whatever element the author wrote the attribute on, and the suites hand them `null`,
+ * `{}`, and `{ getAttribute: () => null }` to exercise the degenerate paths. One check here beats
+ * the same two clauses repeated at every write site.
+ *
+ * @param ledgers - The controller's ledger source, opened over its host element.
+ * @param el - The element about to be written to.
+ * @returns Its memoised ledger, or `null` when there is nothing to write to.
+ * @complexity O(1).
+ */
+export declare function styleOf(ledgers: ElementLedgers, el: Element | null | undefined): StyleLedger | null;
+/**
+ * A controller's claim on the shared per-element ledgers.
+ *
+ * `style` is not guarded — go through {@link styleOf}, which is the one place the "can this object
+ * carry a ledger at all" question is answered.
+ */
+export interface AdvancedLedgers {
+    /** This element's shared ledger, created on first ask by anyone. */
+    style(el: Element): StyleLedger;
+    /**
+     * Give up this controller's claim on every element it wrote to, restoring each one that no other
+     * controller still holds.
+     *
+     * Every element is attempted. One that throws on the way out does not cost the ones after it; the
+     * failures are re-thrown together as an `AggregateError` once the sweep is complete.
+     */
+    restore(): void;
+    /** Elements this controller has asked for. Diagnostics and leak assertions. */
+    elements(): Element[];
+}
+/**
+ * Open one controller's claim on the shared, ref-counted per-element ledgers.
+ *
+ * The registry itself lives in `core/owned-styles.ts` ({@link createStyleClaim}), and that is not
+ * an implementation detail — it is the fix. This tier used to keep a `WeakMap` of its own, holding
+ * one animator's private ledger on behalf of everybody, with a per-entry `foreign` flag deciding
+ * whether the entry was ever restored. Both halves were decided *once*, by whichever controller
+ * arrived first: a second controller's own `hostLedger` was silently ignored, and anything the
+ * first controller flagged foreign was never restored by this path at all, so a property written
+ * by a controller that outlived the animator outlived every restore that would have unwound it.
+ *
+ * Ref-counting removes the flag rather than fixing it. Core's `LedgerSet` is now an owner in the
+ * same registry, so "the animator will restore this one" is no longer a special case a boolean has
+ * to remember — it is simply another claim, and the element is unwound by whichever owner lets go
+ * last, controller or animator.
+ *
+ * There is also no `hostLedger` parameter any more, and its absence is the point. It existed
+ * because this tier ships as its own bundle with its own copy of `owned-styles.ts`, so the
+ * animator's ledger for the host had to be *handed over* to be shared. That made sharing opt-in at
+ * the call site and left two ways to open a capture. The registry now lives on the element itself,
+ * under a `Symbol.for` key both bundles compute identically, so a controller and the animator find
+ * the same entry by asking — and the only way to open a capture is to ask.
+ *
+ * What this tier still needs the registry *for* is what it always did. These controllers write to
+ * elements they merely **found** — a `camera-layer` under a `camera-scene`, a `scene-step` under a
+ * `scene` — and one found element can belong to two controllers. {@link ownedDescendants} removed
+ * the *same-kind* half of that overlap; the cross-kind half is a supported authoring shape (an
+ * element authored `camera-layer z:-100, scene-step from:0 to:1` genuinely has a camera and a scene
+ * writing to it), and a controller constructed directly rather than through `prepare` never went
+ * through the scan at all. Both still need one capture between them.
+ *
+ * @param host - The authored element this controller was prepared on. Released last, for the
+ *   reason `createLedgerSet` documents: the host carries `data-kui-state`, which is the cloak
+ *   layer's release key, so it must not become visible before the subtree under it is back to the
+ *   author's markup.
+ * @complexity O(1) per lookup; O(n) space and O(n) time to restore, in elements written to.
+ */
+export declare function createAdvancedLedgers(host: Element): AdvancedLedgers;
+/**
+ * The descendants carrying `descendantEffect` that `host` actually owns.
+ *
+ * > A host claims a descendant only when no nearer host **of the same kind** sits between them.
+ *
+ * `prepareScene` and `prepareCameraScene` used the raw `[data-kui*="…"]` query, which is
+ * descendant-wide and does not stop at a nested host — so an **outer** host over-reached into an
+ * inner one and both controllers wrote the inner host's children every frame, with different
+ * progress values. Listener and rAF order decided which write survived, which is to say nothing
+ * decided it. {@link createAdvancedLedgers} made that survivable on *teardown* by sharing one
+ * capture per element; it never arbitrated the writes themselves, because `ledger.set()` writes
+ * straight through. This is the other half.
+ *
+ * "Of the same kind" is load-bearing and is not a tidy-up of the rule. An element authored
+ * `camera-layer z:-100, scene-step from:0 to:1` under a `camera-scene` under a `scene` genuinely
+ * has two owners afterwards — a scene and a camera, writing different properties for different
+ * reasons — and `ownership.test.ts`'s 'an element that is both a scene step and a camera layer'
+ * is the standing proof that it still does.
+ *
+ * The `*=` query is a native prefilter and nothing else, so both halves of the rule are predicates
+ * run over what it returned: the candidate must itself *declare* `descendantEffect`, and no nearer
+ * host of `hostEffect`'s kind may stand between it and `host`. The first half is not redundant with
+ * the query. `[data-kui*="camera-layer"]` matches any attribute *containing* that text, which
+ * includes a parameter value — `<img data-kui='fade-up target:".camera-layer"'>` merely names the
+ * class it animates, and the scan used to claim it and write `preserve-3d` and a `translate3d` over
+ * the author's own effect. {@link declaresEffect} is the same name test the parent walk already
+ * uses, applied to the element the walk is about.
+ *
+ * The cost stays O(matched descendants × depth), not a walk of the subtree.
+ *
+ * @param host - The authored element the controller was prepared on.
+ * @param hostEffect - The host's own primitive name, e.g. `scene`. A nearer element declaring it
+ *   is what blocks the claim.
+ * @param descendantEffect - The primitive name to collect, e.g. `scene-step`.
+ * @returns The owned descendants, in document order. Empty when `host` cannot be queried.
+ */
+export declare function ownedDescendants<T extends Element>(host: Element, hostEffect: string, descendantEffect: string): T[];
+export declare function lerp(start: number, end: number, progress: number): number;
+export declare function defaultRaf(win: Window | WindowLike | null | undefined, fn: FrameRequestCallback): number | null;
+export declare function defaultCaf(win: Window | WindowLike | null | undefined, id: number | null | undefined): null;
+/**
+ * `globalThis` rather than the resolved window: the window here is routinely a `WindowLike` double
+ * with four properties on it, and `setTimeout` is not one of them. Falling back to the real global
+ * keeps the default working in every host that has one and leaves injection as the way to control
+ * it, instead of making the default depend on how complete the caller's window happens to be.
+ *
+ * The `as unknown as number` is the usual Node-vs-DOM split — Node's `setTimeout` answers a
+ * `Timeout` object, the DOM's a number — and only the round trip back through `clearTimer` cares.
+ */
+export declare function defaultSetTimer(fn: () => void, ms: number): number | null;
+export declare function defaultClearTimer(id: number | null | undefined): void;
+interface ContextWithEnv {
+    win?: AnyWindow;
+    doc?: AnyDocument;
+    reducedMotion?: boolean | {
+        enabled?: boolean;
+    };
+    createCanvas?: () => HTMLCanvasElement | null;
+    raf?: RafFunction;
+    caf?: CafFunction;
+    setTimer?: SetTimerFunction;
+    clearTimer?: ClearTimerFunction;
+}
+export declare function resolveEnv(ctx?: ContextWithEnv | PrepareContext | null, env?: AdvancedEnv): ResolvedEnv;
+export declare function isReducedMotion(ctx?: ContextWithEnv | PrepareContext | null): boolean;
+export declare function createEffectInstance(opts?: EffectInstanceOptions): EffectInstance;
+export declare function createInertInstance(destroy?: () => void): EffectInstance;
+export declare function registerInto(target: unknown, primitives: Primitive | Primitive[] | unknown, presets: Preset | Preset[] | unknown, name?: string): Registry | Animator;
+export {};

package/dist/types/advanced/camera-3d.d.ts

@@ -0,0 +1,236 @@
+/**
+ * kUInetic 3D Virtual Camera & Depth Projection Module
+ */
+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 WindowLike, type RafFunction, type CafFunction, clamp } from './base.js';
+import { type AudioBand } from './audio.js';
+export { clamp };
+export type CameraParamAccessor = EffectParams | {
+    num?: (name: string, fallback?: number) => number;
+    text?: (name: string, fallback?: string) => string;
+};
+export interface CameraLayer {
+    element: HTMLElement;
+    depthZ: number;
+}
+export interface CameraOptions {
+    depth?: number;
+    mouseTilt?: boolean;
+    /** Which `audio-source` band pushes the camera forward, or absent/null for none. */
+    audio?: AudioBand | null;
+}
+/**
+ * Parse depth value from CSS string.
+ */
+export declare function parseDepth(str?: string | null): number;
+/**
+ * Pure 3D transform calculation for a single layer.
+ */
+export declare function computeLayerTransform(depthZ: number, cameraZ: number, tiltX?: number, tiltY?: number): string;
+export declare class CameraController {
+    container: HTMLElement;
+    options: CameraOptions;
+    env: AdvancedEnv;
+    window: Window | WindowLike | null;
+    raf: RafFunction;
+    caf: CafFunction;
+    layers: CameraLayer[];
+    cameraZ: number;
+    mouse: {
+        x: number;
+        y: number;
+        targetX: number;
+        targetY: number;
+    };
+    rafId: number | null;
+    scrollRafId: number | null;
+    audioRafId: number | null;
+    /** Last value read for the selected band, 0..1. Stays 0 for a scene with no `audio:`. */
+    audioLevel: number;
+    isListening: boolean;
+    /**
+     * Container and every depth layer, each ledger opened at that element's first write and shared
+     * with every other controller writing to the same element — see `createAdvancedLedgers`.
+     *
+     * This used to say "an inner scene claims the outer scene's layers", which is backwards: an
+     * inner `querySelectorAll` only ever sees its own descendants, so it is the **outer** scene that
+     * over-reaches into the inner one. `prepareCameraScene` now scopes the scan with
+     * {@link ownedDescendants}, so an outer camera stops at a nested `camera-scene` and the two no
+     * longer write one layer's `transform` on alternate frames.
+     *
+     * Sharing still matters after that fix, and not only for the controllers built directly by the
+     * suites: a `camera-layer` that is *also* a `scene-step` has two owners by design, because they
+     * are different kinds of host. The ledger is what keeps that case honest.
+     */
+    private ledgers;
+    constructor(container: HTMLElement, options?: CameraOptions, env?: AdvancedEnv);
+    addLayer(element: HTMLElement, depthZ: number): void;
+    applyLayer3D(): void;
+    bindEvents(): void;
+    /**
+     * The 3D space itself: the container's perspective and every layer's `preserve-3d`.
+     *
+     * Separated from {@link start} because the reduced-motion path needs exactly this and none of
+     * the listeners or loops below it — see {@link renderStatic}.
+     */
+    private applyStage;
+    /**
+     * The scene composed once, with the camera parked where its travel begins.
+     *
+     * What a visitor who asked for reduced motion gets instead of nothing, following the decision
+     * `shaders.ts` records: a static frame where one genuinely exists. Here it does, and it is most
+     * of the effect — `depth` and each layer's `z:` *are* the composition, and the scroll only moves
+     * a camera through an arrangement the author already described. One `render()` at `cameraZ = 0`
+     * puts every layer at its authored depth through the container's perspective, so the scene keeps
+     * its real scale hierarchy and simply does not travel. Without it the layers are written nothing
+     * at all and the whole scene collapses flat — the same bug `start()`'s own `render()` call fixed
+     * for the live path.
+     *
+     * Deliberately *not* the scene's end state, which is where the animator leaves a CSS effect under
+     * this policy (`openGate`, `core/animator.ts`). "The end" here is `cameraZ = depth`, i.e. the
+     * camera pushed all the way through: a layer then sits at `z = depthZ + depth / 2`, which against
+     * a `perspective` of `depth` is a 2x blow-up at `z:0` and 10x at `z:400px` of a 1000px scene, with
+     * nearer layers passing the viewer entirely. An end state nobody can see is not a still frame.
+     *
+     * Runs during `prepare`, because it has to — under reduced motion `openGate` marks the element
+     * finished and never activates any instance. See `prepareReducedMotion` in `shaders.ts`.
+     */
+    renderStatic(): void;
+    start(): void;
+    stop(): void;
+    updateScroll(): void;
+    /** The selected band's current value, or 0 for a scene that asked for none. */
+    readAudio(): void;
+    /**
+     * The one frame loop an audio-driven scene runs, doing every read before every write.
+     *
+     * An audio band changes on its own, without a scroll or a pointer move to hang a frame on, so
+     * this scene needs a loop of its own — and then it needs to be the *only* loop, which is why
+     * `onScroll` and `startLoop` both stand down while it is running. Three callbacks each reading
+     * geometry (`getBoundingClientRect`) or style (`readAudioBand`'s computed fallback) and then
+     * writing transforms would force a layout or style recalculation per callback per frame; one
+     * pass that reads scroll position, reads the band, steps the pointer spring and only then
+     * renders forces at most one.
+     */
+    startAudioLoop(): void;
+    onScroll(): void;
+    onMouseMove(e: MouseEvent | {
+        clientX: number;
+        clientY: number;
+    }): void;
+    stepMouse(): boolean;
+    startLoop(): void;
+    /**
+     * Tilt the whole stage toward the pointer.
+     *
+     * The author's own transform is read here, at the first frame that overwrites it, rather than
+     * when the effect activated. Between those two moments sits at least one frame in which the
+     * page's own code can write a transform, and a capture taken at activation would both overwrite
+     * that write and hand the older value back on destroy as if it had never happened.
+     *
+     * `claim()` is what makes that true without a private snapshot field: it remembers `transform`'s
+     * current value the first time this runs and is a no-op on every call after, so `peek()` always
+     * answers with whatever was there just before this method's first write — the ledger already
+     * tracks that for `restore()`; `peek()` is just asking it without writing.
+     */
+    private renderStageTilt;
+    /**
+     * Hand `transform` back when the tilt settles at exactly zero.
+     *
+     * `peek()` reports only what `restore()` would put back, which is the **inline** capture and
+     * nothing else — by design (`owned-styles.ts`, and `test/owned-styles.test.ts` asserts it). So
+     * `peek() || 'rotateX(0deg) rotateY(0deg)'` was right only for an author who had written the
+     * transform inline. For the ordinary case — `.hero { transform: translateY(-20px) }` in a
+     * stylesheet — `peek()` answers `''` and the fallback wrote a *fabricated* identity inline,
+     * which outranks the class and switches the author's own transform off the moment the effect
+     * activates. `start()` renders immediately with the pointer at the synthetic centre, so that is
+     * activation, not some edge case.
+     *
+     * Removing the declaration instead is what actually lands on "the author's own transform": their
+     * inline value if they had one, their stylesheet's if they did not, and nothing at all if
+     * neither. The `removeProperty` is not a ledger bypass — `claim()` above has already recorded
+     * the property, `peek()` answering `''` *is* the ledger saying it found no inline declaration
+     * here, and removal is precisely what its own `restore()` does for that capture.
+     *
+     * Not fixed here: an inline `transform: scale(1.2) !important` comes back through `peek()`
+     * without its priority, so while the effect is live at rest a competing `!important` rule the
+     * author had deliberately beaten wins again. `restore()` puts the priority back, so it ends at
+     * the right value. Closing that needs a per-property give-back on `StyleLedger` (core).
+     *
+     * @complexity O(1).
+     */
+    private restStageTransform;
+    render(): void;
+    /**
+     * `try`/`finally` because the restore must not be hostage to the listener teardown.
+     *
+     * The animator swallows a throwing instance teardown (`runQuietly(() => instance.destroy())`),
+     * and every element this controller reached on its own — the layers — is in no ledger core will
+     * ever restore. A `removeEventListener` the page has replaced, or a window torn down under a
+     * detached document, would otherwise leave `transform` on each layer permanently.
+     */
+    destroy(): void;
+}
+export declare function prepareCameraScene(el: Element, params: EffectParams, ctx?: PrepareContext | null): EffectInstance;
+export declare const CAMERA_PARAMETERS: {
+    depth: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    'mouse-tilt': {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+    /**
+     * Which `audio-source` band pushes the camera forward, if any.
+     *
+     * Same name, same words and the same `off` default as the `shaders` primitive's: one spelling
+     * for "follow this band" across this directory rather than a second word per consumer. Opt-in
+     * for the reason that one is — the value is written by another primitive, and a scene that read
+     * it unasked would start pulsing the moment an unrelated `audio-source` appeared above it.
+     *
+     * Turning it on also changes *how* the scene renders: see `startAudioLoop`, which becomes the
+     * scene's only frame loop.
+     */
+    audio: {
+        type: "keyword";
+        default: string;
+        keywords: string[];
+        cssProperty: string;
+    };
+};
+/**
+ * `camera-layer`'s own parameters. `z` is read straight off the raw `data-kui` attribute by
+ * `prepareCameraScene`'s own regex (see its `layerEls` loop above), not through this primitive's
+ * `prepare` — declaring it here is only what lets the compiler accept `z:-400` on a layer element
+ * instead of warning "unknown parameter" once "unknown effect" (below) is fixed.
+ */
+export declare const CAMERA_LAYER_PARAMETERS: {
+    z: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+};
+/**
+ * `camera-layer` never runs on its own: `prepareCameraScene`'s `[data-kui*="camera-layer"]` scan
+ * reads each layer's `z:` directly off its attribute, and the parent `CameraController` is what
+ * writes `transform`/`transform-style` to it every frame (`applyLayer3D`, `render`). Without a
+ * registered primitive for the name, every `camera-layer` element compiled as an unrecognised
+ * effect — the scene still positioned it correctly, but the console warned "unknown effect
+ * camera-layer" once per layer. This primitive exists only so the name resolves; it deliberately
+ * does nothing of its own.
+ */
+export declare function prepareCameraLayer(): EffectInstance;
+export declare const CAMERA_PRIMITIVES: Primitive[];
+export declare const CAMERA_PRESETS: Preset[];
+export declare function registerCamera(target: unknown): Registry | Animator;

package/dist/types/advanced/fluid-cursor.d.ts

@@ -0,0 +1,149 @@
+/**
+ * kUInetic Fluid Cursor - Interactive Liquid Cursor Trails
+ */
+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 WindowLike, type DocumentLike, type RafFunction, type CafFunction, clamp } from './base.js';
+export { clamp };
+export type FluidParamAccessor = EffectParams | {
+    num?: (name: string, fallback?: number) => number;
+    text?: (name: string, fallback?: string) => string;
+};
+export interface FluidDrop {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    size: number;
+    alpha: number;
+    color: string;
+    viscosity?: number;
+}
+export interface FluidTrailOptions {
+    size?: number;
+    viscosity?: number;
+    color?: string;
+}
+export interface FluidClient {
+    options: FluidTrailOptions;
+    el?: Element;
+}
+export declare function stepFluidDrop(drop: FluidDrop, friction: number): boolean;
+/**
+ * Size the canvas backing store *and* its CSS box from the same numbers.
+ *
+ * The CSS box used to be a fixed `100vw`/`100vh` in {@link FluidTrail.setupCanvas}, which reads
+ * from the visual/layout viewport rather than `window.innerWidth`/`innerHeight`. On iOS Safari with
+ * the address bar visible those two disagree, so the browser scales the backing store to fit the
+ * CSS box and a drop spawned at `clientY` renders off from the pointer — the same defect
+ * `syncCanvasDimensions` (`shaders.ts`) fixes for the shader tier, by the same move: pin the CSS box
+ * to the exact `innerWidth`/`innerHeight` the backing store is derived from, every time either is
+ * synced (see {@link syncCanvasStyleBox}).
+ */
+export declare function syncCanvasSize(canvas: HTMLCanvasElement | null, win: Window | WindowLike | null): number;
+export declare class FluidTrail {
+    options: FluidTrailOptions;
+    env: AdvancedEnv;
+    window: Window | WindowLike | null;
+    document: Document | DocumentLike | null;
+    createCanvas: () => HTMLCanvasElement | null;
+    raf: RafFunction;
+    caf: CafFunction;
+    drops: FluidDrop[];
+    canvas: HTMLCanvasElement | null;
+    ctx: CanvasRenderingContext2D | null;
+    rafId: number | null;
+    isListening: boolean;
+    lastMouse: {
+        x: number;
+        y: number;
+    };
+    hasLastMouse: boolean;
+    wasOutside: boolean;
+    refCount: number;
+    clients: Map<number, FluidClient>;
+    activeClients: Map<number, FluidClient>;
+    private nextClientId;
+    onResize?: () => void;
+    onPointerMove?: (e: PointerEvent | {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    mapKey: object;
+    constructor(options?: FluidTrailOptions, env?: AdvancedEnv);
+    acquire(): boolean;
+    release(): void;
+    registerClient(options: FluidTrailOptions, el?: Element): number;
+    activateClient(id: number): boolean;
+    deactivateClient(id: number): void;
+    /**
+     * Wipe the overlay when the last client stands down.
+     *
+     * `draw()` clears the canvas at the *start* of a frame, so stopping the loop leaves whatever was
+     * in flight painted. The overlay is `position: fixed` at `z-index: 9998` across the whole
+     * viewport, so a `fluid-trail` on `on:pointerenter`/`pointerleave` — or an author's
+     * `control.cancel()` mid-move — left a frozen blob of drops over the entire page until something
+     * reactivated it or the element was destroyed.
+     *
+     * The canvas itself stays mounted on purpose: registration happens at prepare, so the last
+     * *unregister* owns the teardown and no client can have the canvas pulled from under it.
+     *
+     * @complexity O(1).
+     */
+    private clearOverlay;
+    unregisterClient(id: number): void;
+    setupCanvas(): boolean;
+    attachListeners(): void;
+    detachListeners(): void;
+    init(): boolean;
+    private findClientByTarget;
+    private findClientByCoords;
+    resolveClientOwner(e: {
+        clientX: number;
+        clientY: number;
+        target?: EventTarget | null;
+    }): FluidClient | null;
+    getOptionsAt(x: number, y: number): FluidTrailOptions | null;
+    spawnDrop(x: number, y: number, vx: number, vy: number, customOpts?: FluidTrailOptions): void;
+    startLoop(): void;
+    stopLoop(): void;
+    update(): void;
+    draw(): void;
+    destroy(): void;
+}
+export declare function getSharedFluidTrail(env?: AdvancedEnv): FluidTrail;
+/**
+ * Install (or clear) the trail for one document.
+ *
+ * Same asymmetry `setSharedShaderRenderer` closes, for the same reason: `destroy()` deletes only
+ * `this.mapKey`, so an instance stored under a different document's key outlives its own teardown
+ * and is handed to every later lookup for that document with its canvas already removed. The
+ * instance's own key wins; a mismatched caller key is cleared rather than left dangling.
+ */
+export declare function setSharedFluidTrail(instance: FluidTrail | null, env?: AdvancedEnv): void;
+export declare function prepareFluidCursor(el: Element, params: EffectParams, ctx?: PrepareContext | null): EffectInstance;
+export declare const FLUID_PARAMETERS: {
+    size: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    viscosity: {
+        type: "number";
+        default: string;
+        minimum: number;
+        maximum: number;
+        cssProperty: string;
+    };
+    color: {
+        type: "color";
+        default: string;
+        cssProperty: string;
+    };
+};
+export declare const FLUID_PRIMITIVES: Primitive[];
+export declare const FLUID_PRESETS: Preset[];
+export declare function registerFluidCursor(target: unknown): Registry | Animator;

package/dist/types/advanced/gl-utils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Low-level WebGL helper utilities for kUInetic Shaders
+ */
+export interface ProgramLocations {
+    program?: WebGLProgram;
+    a_position?: number;
+    u_image?: WebGLUniformLocation | null;
+    u_image_to?: WebGLUniformLocation | null;
+    u_uvOrigin?: WebGLUniformLocation | null;
+    u_uvScale?: WebGLUniformLocation | null;
+    u_maskBox?: WebGLUniformLocation | null;
+    u_maskRx?: WebGLUniformLocation | null;
+    u_maskRy?: WebGLUniformLocation | null;
+    u_maskAlpha?: WebGLUniformLocation | null;
+    u_time?: WebGLUniformLocation | null;
+    u_strength?: WebGLUniformLocation | null;
+    u_frequency?: WebGLUniformLocation | null;
+    u_chromatic?: WebGLUniformLocation | null;
+    u_iridescence?: WebGLUniformLocation | null;
+    u_mouse?: WebGLUniformLocation | null;
+    u_tint?: WebGLUniformLocation | null;
+    u_color1?: WebGLUniformLocation | null;
+    u_color2?: WebGLUniformLocation | null;
+    u_duotone?: WebGLUniformLocation | null;
+    u_blend?: WebGLUniformLocation | null;
+    u_progress?: WebGLUniformLocation | null;
+    u_seed?: WebGLUniformLocation | null;
+    u_scale?: WebGLUniformLocation | null;
+    u_warp?: WebGLUniformLocation | null;
+    u_grain?: WebGLUniformLocation | null;
+    u_hue?: WebGLUniformLocation | null;
+    u_detail?: WebGLUniformLocation | null;
+    u_bands?: WebGLUniformLocation | null;
+    u_colorCount?: WebGLUniformLocation | null;
+    /** Element 0 of `vec4 u_colors[5]`; one `uniform4fv` of 20 floats fills the whole array. */
+    u_colors?: WebGLUniformLocation | null;
+    /** Which stencil the generative program cuts its field with. See `glyphMask()` in `glsl.ts`. */
+    u_maskMode?: WebGLUniformLocation | null;
+    /** `hover:` as bits — 1 stir, 2 light, 3 both. See `kuiHoverFalloff()` in `glsl.ts`. */
+    u_hover?: WebGLUniformLocation | null;
+    /** The colour the generative field is composited over, straight (non-premultiplied) RGBA. */
+    u_backdrop?: WebGLUniformLocation | null;
+    /** The field's orientation in **radians**; also the axis `motion: drift` travels along. */
+    u_angle?: WebGLUniformLocation | null;
+    /** `motion:` — 0 evolve, 1 drift, 2 swirl. */
+    u_motion?: WebGLUniformLocation | null;
+}
+export declare function compileShader(gl: WebGLRenderingContext | WebGL2RenderingContext, type: number, source: string): WebGLShader | null;
+export declare function createProgram(gl: WebGLRenderingContext | WebGL2RenderingContext, vsSource: string, fsSource: string): WebGLProgram | null;
+export declare function extractLocations(gl: WebGLRenderingContext | WebGL2RenderingContext, program: WebGLProgram | null): ProgramLocations | null;
+export declare function disposeGLResources(gl: WebGLRenderingContext | WebGL2RenderingContext | null, quadBuffer: WebGLBuffer | null, programs: Record<string, ProgramLocations | WebGLProgram | null | undefined>): void;
+export declare function createGLTexture(gl: WebGLRenderingContext | WebGL2RenderingContext, source: TexImageSource): WebGLTexture | null;