How rdev/liquid-glass-react works
Project type + purpose (what you’re diagramming)
This repo is primarily a React UI component library published as liquid-glass-react, implementing Apple-like “Liquid Glass” visuals using shader/refraction-style rendering (likely WebGL/canvas + fragment/vertex shader logic), exposed as a single main component (LiquidGlass) with many visual/interaction props.
Additionally, the repo contains a full demo/consumer application under liquid-glass-example/, implemented as a Next.js app to showcase the library.
So your “system” is not a classic backend system; it’s:
• a library package (build + runtime behavior in the browser), and
• an example web app that depends on it.
1) how the library works internally at runtime (browser rendering pipeline + interactions), and
README insights → key runtime concepts
From the README, the library’s important behaviors are:
• Refraction/displacement (“edgy bending and refraction”)
• Multiple modes: "standard" | "polar" | "prominent" | "shader"
• Blur/frosting, saturation, chromatic aberration
• Hover/click effects, elasticity (“liquid feel”)
• Mouse tracking possibly over:
• component itself, OR
• a larger mouseContainer ref, OR
• external/manual globalMousePos
• Browser support caveat: Safari/Firefox partial support (displacement not visible)
Props → event/mouse tracking → computed effect parameters → shader uniforms → render output.
Library Source (TypeScript/React)
• src/index.tsx
• src/shader-utils.ts
• src/utils.ts
Build/Bundling
• esbuild.config.js
• Outputs: dist/ (not shown in tree but implied) as ESM/CJS + types
Deployment Targets
• npm package artifact
• Next.js static/server deployment (depending on config)
• Library Source → (built by) Build/Bundling → npm package artifact
• Example App → imports → npm package (or local workspace link)
• Example App → deployed to → demo hosting (the README demo URL)
• Blue: Source code containers
• Purple: Build pipeline
• Green: Runtime/deployment artifacts
• Gray: External systems (npm, browser, hosting)
Goal: Show how LiquidGlass works at runtime in the browser.
React Component: LiquidGlass (src/index.tsx)
• Inputs: props (displacementScale, blurAmount, saturation, elasticity, mode, etc.)
• Renders: wrapper DOM + possibly a canvas overlay + children content
Interaction Layer
• Pointer/mouse tracking:
• Source: mouseContainer ref OR component element OR globalMousePos
• Output: normalized mouse position / velocity
• Hover/click state machine:
• hover → highlight/refraction changes
• click → press effect / ripple-like distortion (if implemented)
Rendering/Shader Pipeline (src/shader-utils.ts)
• Initializes WebGL/canvas context
• Loads/compiles shaders (mode "shader" likely uses the most direct shader path)
• Updates uniforms each frame:
• displacementScale, blurAmount, saturation, aberrationIntensity
• mouse position, time, elasticity
• “overLight” toggles highlight/edge behavior
• Produces final composited visual output
Utilities (src/utils.ts)
• Math helpers, clamping, lerp/spring, RAF scheduling, event normalization, etc.
Browser APIs
• DOM (layout, styles)
• Pointer events
• requestAnimationFrame
• WebGL/Canvas rendering
• CSS filters/compositing (if used)
• Props → LiquidGlass → Interaction Layer (configures event sources)
• Mouse events/globalMousePos → Interaction Layer → “Effect State” (mouseX/Y, velocity)
• DOM measurements → Geometry/Layout → Shader uniforms
• Effect State + Geometry → Shader Pipeline → Canvas/WebGL output
• Canvas/WebGL output → visually overlays/underlays children content (compositing relationship)
mode switching:
• mode → selects shader program / algorithm branch:
• standard/polar/prominent/shader → different uniform sets or render paths
• Safari/Firefox partial support → displacement may not render (likely due to WebGL/texture/displacement technique constraints)
Labels for each component
Use file-backed names where possible:
• src/index.tsx (LiquidGlass component)
• src/shader-utils.ts (WebGL/shader helpers)
• src/utils.ts (math/event helpers)
• esbuild.config.js (bundle pipeline)
• liquid-glass-example (Next.js demo)
“Don’t overthink it” but be very detailed: how to maximize component separation here
• Prop Parsing/Defaults
• Event Source Selector (mouseContainer vs local vs globalMousePos)
• Motion Model (elasticity/smoothing)
• Layout Resolver (padding/cornerRadius)
• Mode Router (standard/polar/prominent/shader)
• Shader Program Manager
• Uniform Updater
• RAF Scheduler
• Compositor (how canvas/glass layer overlays children)
• pages/index.tsx (renders examples)
• styling pipeline (globals.css/postcss)
• Next runtime (client-side rendering + optional server aspects)
That combination will be the most accurate representation of this project’s real architecture.