lensfx 0.1.2 → 0.1.3

package/dist/vanilla.d.ts

@@ -0,0 +1,493 @@
+/**
+ * lensfx — Engine Layer: Types & Constants
+ *
+ * Pure TypeScript — no React, no DOM. Can be imported in any environment.
+ */
+/** All optical parameters that control how a single lens looks and distorts. */
+interface LensParams {
+    /** Lens width in pixels. */
+    lensW: number;
+    /** Lens height in pixels. */
+    lensH: number;
+    /** Lens corner radius in pixels. */
+    borderRadius: number;
+    /** Refraction depth/strength — higher = more distortion. Range: 0–10. */
+    depth: number;
+    /** Chromatic aberration split amount. 0 = monochromatic, 1 = full RGB split. */
+    chromaAmount: number;
+    /** Horizontal displacement scale. 0 = no lateral displacement. */
+    scaleX: number;
+    /** Vertical displacement scale. 0 = no vertical displacement. */
+    scaleY: number;
+    /** Resolution of the displacement map canvas (power-of-two recommended). */
+    mapSize: number;
+    /** Gaussian blur radius applied to the background behind the lens (px). */
+    blurAmount: number;
+    /** If true, clips displacement strictly to the lens SDF boundary. */
+    sdfBoundary: boolean;
+    /** If true, applies an erf-smoothed falloff at the lens edge. */
+    edgeFalloff: boolean;
+    /** Additive brightness overlay inside the lens. Positive = lighter, negative = darker. Range: -1 to 1. */
+    brightness: number;
+    /** Intensity of the specular highlight. Range: 0–3. */
+    specularStrength: number;
+    /** Angle of the specular directional light in degrees. */
+    specularRotation: number;
+    /** If true, uses dark (shadow) specular mode instead of bright. */
+    specularDark: boolean;
+    /** Uniform tint applied inside the lens. Range: -1 (black) to 1 (white). */
+    tint: number;
+    /** Strength of the inner glow band. Range: 0–1. */
+    glowStrength: number;
+    /** Angular spread of the glow band, normalised. Range: 0–1. */
+    glowSpread: number;
+    /** Exponent controlling glow falloff curve. Higher = sharper band. */
+    glowExponent: number;
+    /** Strength of the edge specular ring (separate from inner glow). Range: 0–1. */
+    edgeStrength: number;
+    /** Thickness of the edge specular ring in pixels. */
+    edgeWidth: number;
+    /** Exponent controlling edge ring falloff curve. */
+    edgeExponent: number;
+    /** Height of the ellipsoid dome above the lens surface in pixels. */
+    domeDepth: number;
+    /** How much to reduce displacement magnitude at corners (0 = no splay, 1 = full splay). */
+    splayAmount: number;
+    /** Box shadow applied to the lens container (outer drop shadow). */
+    edgeShadow?: string;
+    /** Inset box shadow applied to the lens container. */
+    edgeInsetShadow?: string;
+    /** Secondary rest-state shadow (e.g. when the slider thumb is at rest). */
+    restEdgeShadow?: string;
+}
+/** Precomputed geometric constants for dome curvature. */
+interface DomeConstants {
+    /** Horizontal sphere radius for dome curvature. */
+    Rx: number;
+    /** Vertical sphere radius for dome curvature. */
+    Ry: number;
+    /** Normalised scale factor for the X gradient (trapezoidal integration). */
+    scaleX: number;
+    /** Normalised scale factor for the Y gradient (trapezoidal integration). */
+    scaleY: number;
+}
+/** Input to the synchronous displacement map generator. */
+interface MapGeneratorInput {
+    lensHalfWidth: number;
+    lensHalfHeight: number;
+    borderRadius: number;
+    depth: number;
+    sdfBoundary: boolean;
+    edgeFalloff: boolean;
+    specularRotation: number;
+    glowStrength: number;
+    glowSpread: number;
+    glowExponent: number;
+    edgeStrength: number;
+    edgeWidth: number;
+    edgeExponent: number;
+    domeDepth: number;
+    splayAmount: number;
+}
+/** Output from the displacement map generator. */
+interface MapGeneratorOutput {
+    /** PNG data URL of the generated displacement map. */
+    dataUrl: string;
+    /** Time taken for the pixel loop, in milliseconds. */
+    loopMs: number;
+    /** Time taken for canvas.toDataURL encoding, in milliseconds. */
+    encodeMs: number;
+}
+/** Zero-refraction baseline — all effects disabled. */
+declare const DEFAULT_LENS_PARAMS: LensParams;
+/** LensSwitch base optical parameters. */
+declare const SWITCH_GLASS_DEFAULTS: Partial<LensParams>;
+declare const SWITCH_DARK_OVERRIDES: Partial<LensParams>;
+declare const SWITCH_LIGHT_OVERRIDES: Partial<LensParams>;
+/** LensSlider base optical parameters. */
+declare const SLIDER_GLASS_DEFAULTS: Partial<LensParams>;
+declare const SLIDER_DARK_OVERRIDES: Partial<LensParams>;
+declare const SLIDER_LIGHT_OVERRIDES: Partial<LensParams>;
+declare const SLIDER_SAFARI_OVERRIDES: Partial<LensParams>;
+
+/**
+ * lensfx — Engine Layer: Core Mathematics & Displacement Map Generation
+ *
+ * Pure TypeScript — no React, no DOM references at module load time.
+ * DOM (canvas) is accessed only inside function bodies, never at import time,
+ * making this SSR-safe.
+ */
+
+/**
+ * Approximation of the Gauss error function using hyperbolic tangent.
+ *
+ * erf(x) ≈ tanh(√π · x)
+ *
+ * The constant √π ≈ 1.7724538509 ensures that the derivative at 0 equals
+ * 2/√π (matching the exact erf), giving a C∞ smooth clamping function that
+ * avoids branching and is monotone on (−∞, +∞).
+ */
+declare function erf(x: number): number;
+/**
+ * Computes ellipsoid dome curvature geometry constants for the X and Y axes.
+ *
+ * The dome is modelled as a sphere of radius R that just touches both the
+ * centre and the edge of the lens:  R = (halfDim² + depth²) / (2·depth).
+ *
+ * @param domeDepth - maximum height of the dome above the lens plane (px)
+ * @param halfW     - half-width of the lens (px)
+ * @param halfH     - half-height of the lens (px)
+ */
+declare function computeDomeConstants(domeDepth: number, halfW: number, halfH: number): DomeConstants;
+/**
+ * Evaluates the gradient (surface slope) of the dome at a given offset
+ * from the lens centre.  Returns a value in [0, 1] normalised by `scale`.
+ */
+declare function domeGradient(pos: number, R: number, scale: number): number;
+/**
+ * Builds an SVG feColorMatrix 4×5 matrix string that rescales the
+ * displacement map's R and G channels around the neutral midpoint (128/255 = 0.5).
+ *
+ * When scaleX ≠ scaleY the lens has asymmetric horizontal/vertical displacement
+ * and we normalise the larger axis to 1 so both axes are within [0, 255].
+ */
+declare function colorMatrixValues(ratioX: number, ratioY: number): string;
+/**
+ * Returns a memoised SVG rounded-rectangle mask as a data URI.
+ * Used as CSS `mask-image` on the backdrop-blur and tint layers to
+ * clip them to the lens shape without touching the filter graph.
+ */
+declare function getSvgMaskDataUri(width: number, height: number, radius: number): {
+    uri: string;
+    key: string;
+};
+/**
+ * Creates a stateful, synchronous displacement map generator with:
+ *   • 4-fold quadrant symmetry (75 % fewer pixel evaluations)
+ *   • Reusable canvas & ImageData to avoid GC pressure
+ *   • Cached dome gradient lookup table (recalculated only when geometry changes)
+ *
+ * Use for animated lenses where the map must update every frame in sync with
+ * Framer Motion values.  For static lenses, prefer `generateDisplacementMapAsync`.
+ *
+ * @param mapSize - side length of the square displacement map canvas (px)
+ */
+declare function createDisplacementMapGeneratorSync(mapSize: number): {
+    /**
+     * Generate a new displacement map and return a PNG data URL.
+     * Reuses internal canvas memory; safe to call every animation frame.
+     */
+    generate(input: MapGeneratorInput): MapGeneratorOutput;
+    /** Release canvas memory. Call in React cleanup (useEffect return). */
+    dispose(): void;
+};
+/**
+ * Generates a displacement map asynchronously, processing 64 rows per
+ * animation frame via `setTimeout(0)` to avoid blocking the main thread.
+ *
+ * Returns a Blob Object URL (PNG).  Caller is responsible for calling
+ * `URL.revokeObjectURL` when the Lens unmounts.
+ *
+ * Use for static lenses where the map does not need to update every frame.
+ */
+declare function generateDisplacementMapAsync(canvas: HTMLCanvasElement, params: {
+    canvasSize: number;
+    lensHalfWidth: number;
+    lensHalfHeight: number;
+    borderRadius: number;
+    depth: number;
+    sdfBoundary: boolean;
+    edgeFalloff: boolean;
+    specularRotation?: number;
+    glowStrength?: number;
+    glowSpread?: number;
+    glowExponent?: number;
+    edgeStrength?: number;
+    edgeWidth?: number;
+    edgeExponent?: number;
+    domeDepth?: number;
+    splayAmount?: number;
+}): Promise<string | null>;
+
+/**
+ * lensfx — WebGL Layer: VideoRefractionRenderer
+ *
+ * Full WebGL 1 video refraction engine — Safari fallback for live <video> frames
+ * which cannot be filtered by SVG feDisplacementMap in WebKit.
+ *
+ * Features:
+ * - Analytical circle and rounded-rect bar SDFs
+ * - Multi-control dominant lens tracking with press scaling
+ * - Separable 9-tap Gaussian blur pass (two-pass half-res FBO)
+ * - Chromatic aberration (R, G, B pass)
+ * - Adaptive specular & Apple-style vibrancy luminance correction
+ */
+/** Options for constructing a VideoRefractionRenderer. */
+interface VideoRendererOptions {
+    /** Canvas element to render into. */
+    canvas: HTMLCanvasElement;
+    /** Source video element to sample frames from. */
+    video: HTMLVideoElement;
+    /** Lens depth strength. Default: 2. */
+    depth?: number;
+    /** Chromatic aberration amount (0–1). Default: 0.5. */
+    chromaAmount?: number;
+    /** Angle of specular directional light (degrees). Default: 45. */
+    specularRotation?: number;
+    /** Specular highlight intensity. Default: 1. */
+    specularStrength?: number;
+}
+interface VideoLensConfig {
+    circles: Array<{
+        cx: number;
+        cy: number;
+        radius: number;
+        scale: number;
+        baseScale: number;
+        ratioX: number;
+        ratioY: number;
+    }>;
+    bar?: {
+        cx: number;
+        cy: number;
+        w: number;
+        h: number;
+        radius: number;
+        baseScale: number;
+        ratioX: number;
+        ratioY: number;
+    };
+    bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    bboxSize: {
+        w: number;
+        h: number;
+    };
+    chromaAmount: number;
+    specStrength: number;
+    adaptStrength: number;
+    specLumaLow: number;
+    specLumaHigh: number;
+    hasBlur: boolean;
+}
+declare class VideoRefractionRenderer {
+    private gl;
+    private quadBuffer;
+    private blurProgram;
+    private refractionProgram;
+    private videoTexture;
+    private mapTexture;
+    private blurFboA;
+    private blurTexA;
+    private blurFboB;
+    private blurTexB;
+    private fboWidth;
+    private fboHeight;
+    constructor(canvas: HTMLCanvasElement);
+    setDisplacementMap(image: HTMLImageElement | HTMLCanvasElement): void;
+    private initBlurFBO;
+    render(video: HTMLVideoElement, config: VideoLensConfig): void;
+    dispose(): void;
+}
+
+/**
+ * lensfx — WebGL Layer: QRRefractionRenderer
+ *
+ * Full WebGL 2 (#version 300 es) interactive QR code refraction engine.
+ * Uses an O(1) uniform texture occupancy grid for real-time liquid distortion
+ * through a 33×33 QR matrix.
+ *
+ * Features:
+ * - WebGL 2 (#version 300 es)
+ * - O(1) dot occupancy texture lookup
+ * - Analytical eye rounded-rect SDFs with hover scaling
+ * - Attenuated displacement for eye corner anchors
+ * - Chromatic aberration (scaleR = 1 + 2*chroma, scaleG = 1 + 1*chroma, scaleB = 1)
+ */
+/** Options for constructing a QRRefractionRenderer. */
+interface QRRendererOptions {
+    /** Canvas element to render into. */
+    canvas: HTMLCanvasElement;
+    /** QR matrix data (boolean 33×33 grid, row-major). */
+    qrMatrix: boolean[][];
+    /** Lens depth strength. Default: 2. */
+    depth?: number;
+    /** Chromatic aberration amount (0–1). Default: 0.3. */
+    chromaAmount?: number;
+    /** Dot radius as a fraction of cell size. Default: 0.4. */
+    dotRadius?: number;
+}
+interface QREyeConfig {
+    center: [number, number];
+    half: [number, number, number];
+    radius: [number, number, number];
+    color: [number, number, number];
+    scale: number;
+}
+interface QRRendererInit {
+    canvas: HTMLCanvasElement;
+    size: number;
+    matrixLength: number;
+    occupancyMatrix: Uint8Array;
+    gridOriginUV: number;
+    cellUV: number;
+    dotRadius: number;
+    backgroundColor?: [number, number, number];
+}
+declare class QRRefractionRenderer {
+    private gl;
+    private program;
+    private quadBuffer;
+    private occupancyTexture;
+    private displacementTexture;
+    private paintingTexture;
+    private paintingColorTexture;
+    private matrixLength;
+    private gridOriginUV;
+    private cellUV;
+    private dotRadius;
+    private backgroundColor;
+    constructor(init: QRRendererInit);
+    setDisplacementMap(image: HTMLImageElement | HTMLCanvasElement): void;
+    render(params: {
+        displacementActive: boolean;
+        lensOrigin: [number, number];
+        lensSize: [number, number];
+        displacementScale: [number, number];
+        chromaAmount: number;
+        eyes: QREyeConfig[];
+        eyeRefractionScale?: number;
+    }): void;
+    dispose(): void;
+}
+
+/**
+ * lensfx — Vanilla DOM Engine: createLens
+ *
+ * Zero-dependency, pure DOM + SVG + Canvas optical glass refraction.
+ * Runs anywhere without React, Framer Motion, or bundlers.
+ */
+interface LensOptions {
+    /** Lens width in pixels. Default: 160 */
+    width?: number;
+    /** Alias for width */
+    lensW?: number;
+    /** Lens height in pixels. Default: 100 */
+    height?: number;
+    /** Alias for height */
+    lensH?: number;
+    /** Corner radius in pixels. Default: 24 */
+    radius?: number;
+    /** Alias for radius */
+    borderRadius?: number;
+    /** Lens center X: 0..1 (fraction of container width) or pixel value. Default: 0.5 */
+    x?: number;
+    /** Lens center Y: 0..1 (fraction of container height) or pixel value. Default: 0.5 */
+    y?: number;
+    /** Automatically track pointer / mouse movement over the container element. Default: false */
+    interactive?: boolean;
+    /** Refraction depth / distortion strength (0–10). Default: 2 */
+    depth?: number;
+    /** Chromatic aberration split (0–1). 0 = monochrome, 1 = full RGB split. Default: 0.6 */
+    chroma?: number;
+    /** Alias for chroma */
+    chromaAmount?: number;
+    /** Aspect-ratio displacement scale X (0–1). Default: 0.25 */
+    scaleX?: number;
+    /** Aspect-ratio displacement scale Y (0–1). Default: 0.25 */
+    scaleY?: number;
+    /** Ellipsoid dome height in pixels. Default: 6 */
+    domeDepth?: number;
+    /** Directional specular angle in degrees. Default: 45 */
+    specularRotation?: number;
+    /** Specular highlight intensity. Default: 1 */
+    specularStrength?: number;
+    /** Invert specular to dark shadow mode. Default: false */
+    specularDark?: boolean;
+    /** Clip refraction strictly to the lens SDF boundary. Default: true */
+    sdfBoundary?: boolean;
+    /** Apply erf-smoothed edge falloff. Default: true */
+    edgeFalloff?: boolean;
+    /** Glow intensity (0–1). Default: 0.3 */
+    glowStrength?: number;
+    /** Glow spread factor (0–1). Default: 1 */
+    glowSpread?: number;
+    /** Glow falloff exponent. Default: 1.5 */
+    glowExponent?: number;
+    /** Edge ring highlight intensity (0–1). Default: 0.4 */
+    edgeStrength?: number;
+    /** Edge ring highlight width in pixels. Default: 3 */
+    edgeWidth?: number;
+    /** Splay attenuation factor at corners (0–1). Default: 0.8 */
+    splayAmount?: number;
+    /** Frosted glass blur radius in pixels. Default: 0 */
+    blur?: number;
+    /** Tint color CSS string (e.g. "rgba(255, 255, 255, 0.08)"). Default: "rgba(255, 255, 255, 0.05)" */
+    tintColor?: string;
+    /** Tint backdrop blur in pixels. Default: 0 */
+    tintBlur?: number;
+    /** Tint opacity (0–1). Default: 1 */
+    tintOpacity?: number;
+    /** Lens rim shadow (boolean or custom CSS box-shadow string). Default: true */
+    shadow?: boolean | string;
+    /** Lens rim border (boolean or custom CSS border string). Default: true */
+    border?: boolean | string;
+    /** Displacement map resolution in pixels. Default: 256 */
+    mapSize?: number;
+    /** Pre-rendered displacement map data URL. */
+    displacementMapUrl?: string;
+    /** Alternative element / selector to apply the filter to instead of container */
+    refractionTarget?: HTMLElement | string;
+    /** Callback fired when displacement map data URL changes */
+    onMapChange?: (url: string) => void;
+    /** Callback fired when lens position changes */
+    onPositionChange?: (x: number, y: number) => void;
+}
+interface LensInstance {
+    /** The container element */
+    el: HTMLElement;
+    /** The element receiving the SVG displacement filter */
+    targetEl: HTMLElement;
+    /** The hidden SVG root element housing the filter defs */
+    svgEl: SVGSVGElement;
+    /** The SVG filter element */
+    filterEl: SVGFilterElement;
+    /** The floating lens overlay element (rim lighting, border, tint) */
+    overlayEl: HTMLElement;
+    /** Current active options */
+    options: LensOptions;
+    /** Current displacement map data URL */
+    mapDataUrl: string;
+    /** Move lens to new x, y position (pixel or 0..1 normalized) */
+    setPosition: (x: number, y: number) => void;
+    /** Update lens options dynamically */
+    update: (newOptions: Partial<LensOptions>) => void;
+    /** Toggle interactive mouse/pointer tracking */
+    setInteractive: (interactive: boolean) => void;
+    /** Destroy the lens and restore all DOM modifications */
+    destroy: () => void;
+}
+/**
+ * Creates a real optical glass refraction lens on any DOM element.
+ *
+ * @param target - Target container element or CSS selector string
+ * @param options - Optical and behavioral options
+ * @returns LensInstance with control methods (setPosition, update, destroy)
+ *
+ * @example
+ * ```js
+ * const lens = lensfx.createLens(document.querySelector("#card"), {
+ *   width: 200,
+ *   height: 120,
+ *   radius: 28,
+ *   interactive: true,
+ * });
+ * ```
+ */
+declare function createLens(target: HTMLElement | string, options?: LensOptions): LensInstance;
+
+export { DEFAULT_LENS_PARAMS, type DomeConstants, type LensInstance, type LensOptions, type LensParams, type MapGeneratorInput, type MapGeneratorOutput, QRRefractionRenderer, type QRRendererOptions, SLIDER_DARK_OVERRIDES, SLIDER_GLASS_DEFAULTS, SLIDER_LIGHT_OVERRIDES, SLIDER_SAFARI_OVERRIDES, SWITCH_DARK_OVERRIDES, SWITCH_GLASS_DEFAULTS, SWITCH_LIGHT_OVERRIDES, VideoRefractionRenderer, type VideoRendererOptions, colorMatrixValues, computeDomeConstants, createDisplacementMapGeneratorSync, createLens, domeGradient, erf, generateDisplacementMapAsync, getSvgMaskDataUri };