lensfx 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to `lensfx` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-10-17
+
+### Added
+
+#### Engine Layer (`lensfx`)
+- Pure mathematical optics engine:
+  - Error function (`erf`) calculation for Gaussian surface profiles.
+  - Optical dome constant calculation (`computeDomeConstants`).
+  - Radial gradient generation for spherical dome profiles (`domeGradient`).
+  - SVG `feColorMatrix` calculation for aspect ratio corrections (`colorMatrixValues`).
+  - SVG mask URI generation for rounded-rectangle lens clipping (`getSvgMaskDataUri`).
+  - Real-time and asynchronous displacement map generator (`createDisplacementMapGeneratorSync`, `generateDisplacementMapAsync`).
+  - Pre-calibrated lens optical constants (`SWITCH_GLASS_DEFAULTS`, `SLIDER_GLASS_DEFAULTS`, dark/light theme overrides).
+
+#### Primitives Layer
+- `<Lens>` unstyled behavioral glass component:
+  - SVG `feDisplacementMap` real-time DOM refraction (preserves text selection, pointer events, form inputs).
+  - Chromatic aberration separation (red, green, blue optical channels).
+  - Multi-lens context support (`Lens.General` / `Lens.Group`) for sharing one background across multiple moving lenses.
+  - Offscreen generation pausing (`pauseOffscreen`) via `IntersectionObserver`.
+  - Motion value interpolation for 60fps gesture and scroll-driven physics via Framer Motion.
+
+#### Components Layer
+- `<LensSwitch>` accessible glass toggle switch with spring physics, keyboard support (Space / Enter), and full controlled/uncontrolled state.
+- `<LensSlider>` accessible optical glass range slider with tick quantization, track fill refraction, and thumb dome physics.
+- `<LensToggleGroup>` segmented radio control with real-time sliding optical lens and glowing active indicator.
+
+#### WebGL Layer
+- `VideoRefractionRenderer` WebGL 1 shader fallback for live HTML5 `<video>` elements on WebKit / Safari.
+- `QRRefractionRenderer` WebGL 2 (#version 300 es) interactive QR code refraction engine with O(1) uniform texture lookup.
+
+#### Design Tokens
+- Design token stylesheet `lensfx/styles` (`dist/lensfx.css`) providing namespaced CSS custom properties (`--lensfx-*`) for colors, radii, shadows, animations, auto dark-mode (`prefers-color-scheme`), and accessibility (`prefers-reduced-motion`, `:focus-visible`).
+
+#### Developer Experience & Tooling
+- Dual ESM and CJS bundle output with TypeScript declarations (`tsup`).
+- `"use client"` directive injection for Next.js App Router (RSC) compatibility.
+- Tree-shaking enabled with `sideEffects: ["*.css"]`.
+- Comprehensive Vitest unit & integration test suite (50 tests covering pure math, switch, slider, and toggle group).
+- Size-limit bundle gate (core engine < 10 kB, full library < 80 kB).
+- GitHub Actions CI workflow for type checking, testing, building, and bundle size tracking.
+
+## [0.1.0] - 2026-10-16
+
+### Added
+- Initial experimental release of reverse-engineered glass simulation engine.

package/README.md

@@ -1,184 +1,380 @@
-# LensFX (Aave Glass Optical Refraction Engine)
+# lensfx
 
-> 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**.
+**The most convincing, drop-in optical glass refraction for the web.**
+
+[![npm version](https://img.shields.io/npm/v/lensfx)](https://www.npmjs.com/package/lensfx)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/lensfx)](https://bundlephobia.com/package/lensfx)
+[![license](https://img.shields.io/npm/l/lensfx)](./LICENSE)
+[![CI](https://github.com/rudraksha132/lensfx/actions/workflows/ci.yml/badge.svg)](https://github.com/rudraksha132/lensfx/actions)
+
+Real optical refraction — not blur, not `backdrop-filter`, not a fake glass card.  
+Real DOM elements (text, links, inputs, images) refracted in place using physics-derived SVG displacement maps.
 
 ---
 
-## 1. Architectural Overview
+## Who it's for
+
+App developers who want a glass effect without learning SVG filters, WebGL, or optical physics.
+
+## What it does best
+
+The most convincing, drop-in refraction on the web. `<LensSwitch>`, `<LensSlider>`, and `<LensToggleGroup>` all look and feel like real glass — because they simulate real lenses, not a CSS shortcut.
 
-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.
+## What it refuses to do
+
+No full design system, no CSS framework, no state management. The narrow scope is what keeps the API small and the bundle light.
 
 ---
 
-## 2. Directory Structure
+## Quick start
 
+```bash
+npm install lensfx framer-motion
 ```
-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
+
+```tsx
+import "lensfx/styles";
+import { Lens } from "lensfx";
+
+export default function App() {
+  return (
+    <div style={{ background: "url('/hero.jpg') center/cover", width: 400, height: 300 }}>
+      <Lens
+        lens={{
+          lensW: 120,
+          lensH: 80,
+          borderRadius: 20,
+          depth: 2,
+          domeDepth: 6,
+          chromaAmount: 0.8,
+          specularStrength: 1.2,
+          specularRotation: 45,
+          sdfBoundary: true,
+          edgeFalloff: true,
+          glowStrength: 0.4,
+        }}
+        x={0.5}
+        y={0.5}
+      >
+        <p style={{ color: "white" }}>Drag me</p>
+      </Lens>
+    </div>
+  );
+}
 ```
 
+That's it. Zero configuration for a working lens.
+
 ---
 
-## 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]
+## Components
+
+### `<Lens>` — primitive (unstyled)
+
+The single behavioral primitive. All other components compose over this.
+
+```tsx
+import { Lens } from "lensfx";
+
+<Lens
+  lens={params}          // LensParams — all optical controls
+  x={0.5}               // normalised (0–1) or px position
+  y={0.5}
+  lensW={120}           // override width (or MotionValue)
+  lensH={80}            // override height (or MotionValue)
+  borderRadius={20}     // or MotionValue
+  tintColor="white"     // CSS color string
+  tintOpacity={0.1}     // or MotionValue
+  tintBlur={4}          // backdrop blur inside lens (px)
+  refractionTarget={<MyBackground />}  // alternative target element
+  pauseOffscreen        // stop generating maps when not visible
+  className="my-lens"
+  style={{ cursor: "grab" }}
+>
+  {children}            // rendered on top of the distortion
+</Lens>
+```
+
+#### `Lens.General` — multi-lens provider
+
+Share one refraction context across many lenses (e.g. a moving spotlight over a page):
+
+```tsx
+<Lens.General.Provider>
+  <Lens.General.Target>
+    <p>This text gets refracted by any lens above it.</p>
+  </Lens.General.Target>
+</Lens.General.Provider>
 ```
-This achieves sub-2ms generation times on standard hardware.
 
 ---
 
-## 4. SVG Filter Pipeline
+### `<LensSwitch>`
 
-The dynamic SVG filter rendered in `<AaveGlass>`:
+A toggle switch with rubber-band drag, squish physics, and live refraction of the track behind the thumb.
+
+```tsx
+import { LensSwitch } from "lensfx";
+
+// Uncontrolled
+<LensSwitch
+  defaultChecked
+  ariaLabel="Enable notifications"
+  onCheckedChange={(checked) => console.log(checked)}
+/>
+
+// Controlled
+<LensSwitch
+  checked={isEnabled}
+  onCheckedChange={setIsEnabled}
+  ariaLabel="Enable notifications"
+  theme="light"
+  width={90}
+  height={34}
+/>
+```
 
-```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" />
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | — | Controlled checked state |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled default |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Change handler |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `ariaLabel` | `string` | `"Switch"` | Accessible label |
+| `theme` | `"dark" \| "light"` | `"dark"` | Adjusts specular and brightness |
+| `width` | `number` | `74` | Track width in px |
+| `height` | `number` | `28` | Track height in px |
+| `lens` | `Partial<LensParams>` | — | Override optical parameters |
+| `rubberOvershoot` | `number` | `0.15` | Max rubber-band overdrag (fraction of width) |
 
-  <!-- 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" />
+### `<LensSlider>`
 
-  <!-- 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" />
+A range slider where the thumb is a glass lens gliding over a coloured progress track.
 
-  <!-- 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" />
+```tsx
+import { LensSlider } from "lensfx";
+
+// Uncontrolled
+<LensSlider
+  defaultValue={30}
+  min={0}
+  max={100}
+  step={1}
+  ariaLabel="Volume"
+  onValueChange={(val) => console.log(val)}
+/>
+
+// Controlled
+<LensSlider
+  value={volume}
+  onValueChange={setVolume}
+  ariaLabel="Volume"
+  theme="light"
+  width={240}
+/>
+```
 
-  <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" />
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | — | Controlled value |
+| `defaultValue` | `number` | `50` | Uncontrolled default |
+| `onValueChange` | `(val: number) => void` | — | Change handler |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step size |
+| `ariaLabel` | `string` | `"Slider"` | Accessible label |
+| `theme` | `"dark" \| "light"` | `"dark"` | Adjusts specular and brightness |
+| `width` | `number` | `240` | Total width in px |
 
-  <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" />
+### `<LensToggleGroup>`
 
-  <!-- 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" />
+A segmented control where a glass pill springs between options.
 
-  <!-- 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>
+```tsx
+import { LensToggleGroup, ToggleOption } from "lensfx";
+
+const options: ToggleOption[] = [
+  { id: "day",   label: "Day",   activeColor1: "#fbbf24", activeColor2: "#f59e0b" },
+  { id: "week",  label: "Week",  activeColor1: "#38bdf8", activeColor2: "#0284c7" },
+  { id: "month", label: "Month", activeColor1: "#a78bfa", activeColor2: "#7c3aed" },
+];
+
+// Uncontrolled
+<LensToggleGroup options={options} defaultValue="week" />
+
+// Controlled
+<LensToggleGroup
+  options={options}
+  value={period}
+  onValueChange={setPeriod}
+  theme="light"
+/>
 ```
 
 ---
 
-## 5. WebGL Fallback Pipelines
+## Optical parameters (`LensParams`)
+
+Every component accepts a `lens` prop to override these. All values are optional:
+
+```tsx
+<LensSwitch lens={{ domeDepth: 8, chromaAmount: 1.5 }} />
+```
 
-### 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}$$
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `lensW` | `number` | `90` | Lens width (px) |
+| `lensH` | `number` | `60` | Lens height (px) |
+| `borderRadius` | `number` | `0` | Corner radius (px) |
+| `depth` | `number` | `0` | Refraction magnitude (0–10) |
+| `domeDepth` | `number` | `0` | Ellipsoid dome height above lens plane (px) |
+| `chromaAmount` | `number` | `0` | RGB split (0–1) |
+| `scaleX` | `number` | `0` | Horizontal displacement scale |
+| `scaleY` | `number` | `0` | Vertical displacement scale |
+| `sdfBoundary` | `boolean` | `false` | Clip displacement to lens SDF boundary |
+| `edgeFalloff` | `boolean` | `false` | Smooth erf() rolloff at edges |
+| `specularStrength` | `number` | `0` | Highlight intensity |
+| `specularRotation` | `number` | `0` | Light angle (degrees) |
+| `glowStrength` | `number` | `0` | Inner glow band (0–1) |
+| `brightness` | `number` | `0` | Brightness overlay (-1 to 1) |
+| `tint` | `number` | `0` | White (positive) or black (negative) tint |
+| `splayAmount` | `number` | `0` | Corner displacement attenuation |
+| `blurAmount` | `number` | `0` | Frosted glass blur radius (px) |
+| `mapSize` | `number` | `256` | Displacement map resolution |
 
-### 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.
+---
+
+## Engine API (advanced)
+
+For custom lenses or non-React environments:
+
+```ts
+import {
+  erf,
+  computeDomeConstants,
+  createDisplacementMapGeneratorSync,
+  generateDisplacementMapAsync,
+  colorMatrixValues,
+  getSvgMaskDataUri,
+} from "lensfx";
+
+// Generate a displacement map on every animation frame
+const gen = createDisplacementMapGeneratorSync(256);
+const { dataUrl, loopMs } = gen.generate({
+  lensHalfWidth: 60,
+  lensHalfHeight: 30,
+  borderRadius: 15,
+  depth: 2,
+  sdfBoundary: true,
+  edgeFalloff: true,
+  specularRotation: 45,
+  glowStrength: 0.5,
+  glowSpread: 0.5,
+  glowExponent: 1.5,
+  edgeStrength: 0,
+  edgeWidth: 3,
+  edgeExponent: 1.5,
+  domeDepth: 5,
+  splayAmount: 0.4,
+});
+
+// Plug into an SVG feDisplacementMap manually:
+feImageEl.setAttribute("href", dataUrl);
+filterEl.id = `my-lens-v${version}`;
+targetEl.style.filter = `url(#${filterEl.id})`;
+
+// When done:
+gen.dispose();
+```
 
 ---
 
-## 6. Component Physics & Interaction Mechanics
+## WebGL renderers (Safari / video)
 
-### 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)$$
+Safari cannot apply SVG `feDisplacementMap` to live `<video>` frames.
+Use the WebGL fallback:
 
-### 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})$$
+```ts
+import { VideoRefractionRenderer } from "lensfx";
+
+const renderer = new VideoRefractionRenderer({
+  canvas: canvasEl,
+  video: videoEl,
+  depth: 2,
+  chromaAmount: 0.5,
+  specularRotation: 45,
+  specularStrength: 1,
+});
+
+// Call on every animation frame:
+renderer.render({ lensX: 200, lensY: 150, lensW: 120, lensH: 80, borderRadius: 20 });
+```
 
 ---
 
-## 7. Quick Usage Example
+## Styling & CSS tokens
 
-```tsx
-import { GlassSwitch, GlassSlider, GlassToggleGroup } from "./src";
+Import the stylesheet once at your app root:
 
-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>
-  );
+```ts
+import "lensfx/styles";
+```
+
+Override any token:
+
+```css
+:root {
+  --lensfx-primary: #a78bfa;   /* purple accent */
+  --lensfx-bg-2: #1e1b4b;      /* indigo background */
+  --lensfx-radius-full: 9999px;
 }
 ```
+
+All CSS variables are prefixed `--lensfx-` and listed in [`src/lensfx.css`](./src/lensfx.css).
+
+---
+
+## Accessibility
+
+- `<LensSwitch>` renders a real `<input type="checkbox" role="switch">`. Space and Enter toggle it. Screen readers announce state correctly.
+- `<LensSlider>` renders a real `<input type="range">`. Arrow keys, Home, End all work natively.
+- `<LensToggleGroup>` uses `role="radio"` on each button with `aria-checked`.
+- Refraction is **purely visual** — it does not change focus order, hit-testing, or text selection.
+- `prefers-reduced-motion` is respected: animations are disabled.
+- `prefers-color-scheme` is respected by the CSS token file.
+
+---
+
+## Browser support & limitations
+
+| Browser | SVG Refraction | Video Refraction |
+|---|---|---|
+| Chrome / Edge | ✅ Full | ✅ Full |
+| Firefox | ✅ Full | ✅ Full |
+| Safari (desktop) | ✅ Full | ⚠️ Use `VideoRefractionRenderer` |
+| Safari (iOS) | ✅ (pixel coords mode) | ⚠️ Use `VideoRefractionRenderer` |
+
+**Performance notes**:
+- The displacement map is generated on the CPU. For large lenses (> 200 × 200 px), `mapSize: 128` provides a good quality/performance trade-off.
+- The `pauseOffscreen` prop stops map generation when the lens is scrolled out of view — highly recommended for long pages.
+- Map generation is 4× faster thanks to quadrant symmetry; it typically takes 1–3 ms on modern hardware at 256 × 256.
+
+---
+
+## Roadmap
+
+- [ ] Playwright visual regression tests (Chromium, Firefox, WebKit)
+- [ ] Storybook documentation site
+- [ ] Vue 3 adapter (`@lensfx/vue`)
+- [ ] `<LensCard>` opinionated card component
+- [ ] Svelte adapter
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).