lensfx 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rudraksha132
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# LensFX (Aave Glass Optical Refraction Engine)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Optical glass simulation and refraction engine for modern web apps.  
+> Reverse-engineered from `https://aave.com/design/building-glass-for-the-web`.  
+> Stack: **React 18+**, **Framer Motion**, **SVG Filters**, **WebGL / WebGL 2**.
+
+---
+
+## 1. Architectural Overview
+
+LensFX brings real-time optical physics to the DOM and WebGL without resorting to expensive offscreen canvas rasterizers like `html2canvas`. Real DOM elements (text, links, buttons, inputs) remain fully interactive, selectable, and accessible behind the lens.
+
+---
+
+## 2. Directory Structure
+
+```
+d:/cf/aave/
+├── src/
+│   ├── index.ts                   # Unified library entry point
+│   ├── lib/
+│   │   └── glass/
+│   │       ├── types.ts           # Lens parameters, theme overrides, slot interfaces
+│   │       ├── math.ts            # SDF, erf, dome constants, sync/async map generators
+│   │       └── AaveGlass.tsx      # Core <AaveGlass> component & multi-lens manager
+│   ├── components/
+│   │   ├── GlassSwitch.tsx        # Switch with rubber-band overshoot & squish physics
+│   │   ├── GlassSlider.tsx        # Range slider with track fill refraction target
+│   │   ├── GlassToggleGroup.tsx   # Segmented control with spring-eased refraction pill
+│   │   └── GlassPlayground.tsx    # Live benchmark & parameter exploration stage
+│   └── webgl/
+│       ├── VideoRefractionRenderer.ts  # WebGL video player glass engine & shaders
+│       └── QRRefractionRenderer.ts     # WebGL 2 interactive QR code refraction engine
+└── README.md
+```
+
+---
+
+## 3. Mathematical Foundations
+
+### 3.1 Signed Distance Function (SDF) of Rounded Rectangle
+The displacement map calculates pixel distance from the rounded rectangle lens:
+$$\text{ox} = \frac{\text{col} + 0.5}{\text{size}} \cdot 2 \cdot \text{halfW} - \text{halfW}$$
+$$\text{oy} = \frac{\text{row} + 0.5}{\text{size}} \cdot 2 \cdot \text{halfH} - \text{halfH}$$
+$$d_x = \max(|\text{ox}| - \text{halfW} + R, 0), \quad d_y = \max(|\text{oy}| - \text{halfH} + R, 0)$$
+$$\text{sdf} = \sqrt{d_x^2 + d_y^2} + \min(\max(|\text{ox}| - \text{halfW} + R, |\text{oy}| - \text{halfH} + R), 0) - R$$
+
+### 3.2 Error Function (`erf`) Approximation
+Used for smooth edge falloff without performance penalties:
+$$\text{erf}(x) = \tanh(1.7724538509 \cdot x), \quad \text{where } \sqrt{\pi} \approx 1.7724538509$$
+$$\text{falloff} = 0.5 \cdot \left(1 + \text{erf}\left(\text{innerSDF} \cdot \frac{1}{\text{depth} \cdot \sqrt{2}}\right)\right)$$
+
+### 3.3 3D Dome Geometry Integration
+For parabolic / spherical curvature (`domeDepth > 0`):
+$$a = \max(0.01, \min(\text{domeDepth}, \min(\text{halfW}, \text{halfH}) - 1))$$
+$$R_x = \frac{\text{halfW}^2 + a^2}{2a}, \quad R_y = \frac{\text{halfH}^2 + a^2}{2a}$$
+Numerical integration over 200 samples computes normalisation factors `scaleX` and `scaleY` so the integral sums to $0.5$:
+$$\nabla_{\text{dome}}(p, R) = \frac{\min(p, 0.999R)}{\sqrt{R^2 - \min(p, 0.999R)^2}} \cdot \text{scale}$$
+
+### 3.4 Four-Fold Quadrant Symmetry
+For dynamic lenses, the top-left quadrant $[0 \dots \frac{\text{size}}{2}, 0 \dots \frac{\text{size}}{2}]$ is computed once and written directly into all 4 quadrants of the `ImageData` buffer simultaneously:
+```javascript
+// Top-Left:      (col, row)
+// Top-Right:     (size - 1 - col, row)             [negate R displacement]
+// Bottom-Left:   (col, size - 1 - row)             [negate G displacement]
+// Bottom-Right:  (size - 1 - col, size - 1 - row)   [negate R & G displacement]
+```
+This achieves sub-2ms generation times on standard hardware.
+
+---
+
+## 4. SVG Filter Pipeline
+
+The dynamic SVG filter rendered in `<AaveGlass>`:
+
+```xml
+<filter filterUnits="objectBoundingBox" primitiveUnits="objectBoundingBox"
+        color-interpolation-filters="sRGB" x="0" y="0" width="1" height="1">
+  <!-- 1. Neutral gray background (128, 128, 128) -->
+  <feFlood floodColor="rgb(128,128,128)" floodOpacity="1" result="mapBg" />
+
+  <!-- 2. Dynamic Displacement Map -->
+  <feImage href="{dataUrl}" preserveAspectRatio="none" result="rawMap"
+           x="{lensLeft}" y="{lensTop}" width="{lensW}" height="{lensH}" />
+
+  <!-- 3. Composite over neutral gray outside lens -->
+  <feComposite in="rawMap" in2="mapBg" operator="over" result="map" />
+
+  <!-- 4. Aspect-ratio scaling feColorMatrix -->
+  <feColorMatrix in="map" type="matrix"
+    values="{Sx} 0 0 0 {0.5*(1-Sx)}  0 {Sy} 0 0 {0.5*(1-Sy)}  0 0 1 0 0  0 0 0 1 0"
+    result="scaledMap" />
+
+  <!-- 5. Chromatic Aberration 3-Pass Displacement -->
+  <feDisplacementMap in="SourceGraphic" in2="scaledMap"
+    scale="{maxScale * (1 + 0.2 * chroma)}" xChannelSelector="R" yChannelSelector="G" />
+  <feColorMatrix type="matrix" values="1 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0" result="dispR" />
+
+  <feDisplacementMap in="SourceGraphic" in2="scaledMap"
+    scale="{maxScale * (1 + 0.1 * chroma)}" xChannelSelector="R" yChannelSelector="G" />
+  <feColorMatrix type="matrix" values="0 0 0 0 0  0 1 0 0 0  0 0 0 0 0  0 0 0 1 0" result="dispG" />
+
+  <feDisplacementMap in="SourceGraphic" in2="scaledMap"
+    scale="{maxScale}" xChannelSelector="R" yChannelSelector="G" />
+  <feColorMatrix type="matrix" values="0 0 0 0 0  0 0 0 0 0  0 0 1 0 0  0 0 0 1 0" result="dispB" />
+
+  <feComposite in="dispR" in2="dispG" operator="arithmetic" k1="0" k2="1" k3="1" k4="0" />
+  <feComposite in2="dispB" operator="arithmetic" k1="0" k2="1" k3="1" k4="0" result="lensResult" />
+
+  <!-- 6. Specular Highlight Pass -->
+  <!-- Light Theme: Additive Specular -->
+  <feColorMatrix in="{isSafari ? 'rawMap' : 'map'}" type="matrix"
+    values="0 0 0 0 1  0 0 0 0 1  0 0 0 0 1  0 0 1 0 {-128/255}" result="specMask" />
+  <feComposite in="specMask" in2="lensResult" operator="arithmetic"
+    k1="0" k2="{specularStrength}" k3="1" k4="0" result="lensResult" />
+
+  <!-- 7. Hole Cutout & Over Composite -->
+  <feFlood floodColor="black" floodOpacity="1" result="lensMask" />
+  <feComposite in="SourceGraphic" in2="lensMask" operator="out" result="holedSG" />
+  <feComposite in="lensResult" in2="holedSG" operator="over" />
+</filter>
+```
+
+---
+
+## 5. WebGL Fallback Pipelines
+
+### 5.1 Video Player Refraction (`VideoRefractionRenderer.ts`)
+* **Analytical SDF Evaluation**: Evaluates 3 circle controls and 1 rounded-rectangle seek bar analytically in the fragment shader.
+* **Separable 9-Tap Blur**: Runs a half-resolution 2-pass blur using kernel:
+  `[0.0276, 0.0663, 0.1240, 0.1801, 0.2042, 0.1801, 0.1240, 0.0663, 0.0276]`
+* **Apple-Style Vibrancy**: Dynamically balances specular highlight between additive (dark background) and multiplicative (bright background) based on perceptual luminance:
+  $$\text{luma} = 0.299R + 0.587G + 0.114B$$
+  $$\text{correction} = (0.5 - \text{luma}) \cdot \text{adaptStrength} \cdot \text{mask}$$
+
+### 5.2 QR Code Refraction (`QRRefractionRenderer.ts`)
+* **WebGL 2 (`#version 300 es`)**: Uses integer texelFetch into an `R8` occupancy texture for $O(1)$ grid lookup.
+* **Analytical Finder Eye SDFs**: Renders three corner detection eyes with animated hover scales and attenuated refraction displacement.
+
+---
+
+## 6. Component Physics & Interaction Mechanics
+
+### Rubber-Band Overshoot Formula
+Used across `<GlassSwitch>` and `<GlassSlider>`:
+$$f(x) = \text{maxOvershoot} \cdot \left(1 - \left(1 - \min\left(1, \frac{x}{\text{dampening}}\right)\right)^3\right)$$
+
+### Perpendicular Squish Simulation Loop
+Models velocity-induced lens deformation with a damped harmonic oscillator:
+$$\text{targetSquish} = \min\left(0.35, \max(0.012 \cdot |\text{velocity}|^{0.75}, \text{hold})\right)$$
+$$a = -180 \cdot (\text{squish} - \text{targetSquish}) - 14 \cdot \text{squishVelocity}$$
+$$\text{lensWidth} = W_{\text{base}} \cdot (1 - 0.2 \cdot \text{squish})$$
+$$\text{lensHeight} = H_{\text{base}} \cdot (1 + 0.4 \cdot \text{squish})$$
+
+---
+
+## 7. Quick Usage Example
+
+```tsx
+import { GlassSwitch, GlassSlider, GlassToggleGroup } from "./src";
+
+export function Demo() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px", padding: "40px" }}>
+      {/* Switch */}
+      <GlassSwitch defaultChecked={true} theme="dark" />
+
+      {/* Slider */}
+      <GlassSlider defaultValue={50} min={0} max={100} theme="dark" />
+
+      {/* Toggle Group */}
+      <GlassToggleGroup
+        options={[
+          { id: "hubs", label: "Hubs" },
+          { id: "spokes", label: "Spokes" },
+          { id: "reserves", label: "Reserves" },
+        ]}
+        defaultValue="hubs"
+        theme="dark"
+      />
+    </div>
+  );
+}
+```