# samasante/liquid-glass architecture

> Architecture diagram of the GitHub repository samasante/liquid-glass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samasante/liquid-glass
- Repository: https://github.com/samasante/liquid-glass

## Overview

liquid-glass is a headless React lens library for refracting live DOM, copied content, and video/canvas surfaces, with a companion interactive site for trying and learning the API. The main user workflow is to configure a Glass lens and optics, then render it through the DOM or WebGL path; motion values can drive lens geometry. The site exposes a playground, examples, and documentation. Some site and renderer internals were not sampled, so unsourced implementation details and links are omitted.

Main entry points: [`site/src/views/Examples.tsx`](https://github.com/samasante/liquid-glass/blob/main/site/src/views/Examples.tsx) (Examples gallery), [`site/src/views/Playground.tsx`](https://github.com/samasante/liquid-glass/blob/main/site/src/views/Playground.tsx) (Playground view), [`site/src/views/Docs.tsx`](https://github.com/samasante/liquid-glass/blob/main/site/src/views/Docs.tsx) (Documentation view), [`src/Glass.tsx`](https://github.com/samasante/liquid-glass/blob/main/src/Glass.tsx) (Glass component)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["React Lens API"]
  node_entry["Public exports<br/>[index.ts]"]
  node_glass["Glass component<br/>[Glass.tsx]"]
  node_interaction["Interaction utilities<br/>[interaction.tsx]"]
end

subgraph group_engine["Refraction Engine"]
  node_material["DOM material<br/>[GlassMaterial.tsx]"]
  node_displacement["Displacement maps<br/>[displacement.ts]"]
  node_signals["Motion values<br/>[signal.ts]"]
  node_surface["WebGL surfaces<br/>[GlassSurface.tsx]"]
  node_webgl["WebGL renderer<br/>[glassWebGL.ts]"]
end

subgraph group_site["Interactive Site"]
  node_siteapp["Site app router<br/>[main.tsx]"]
  node_router["View navigation<br/>[router.ts]"]
  node_playground["Playground view<br/>[Playground.tsx]"]
  node_demo["Live glass demo<br/>[GlassDemo.tsx]"]
  node_controls["Optics controls"]
  node_docs["Documentation view<br/>[Docs.tsx]"]
  node_examplesview["Examples gallery<br/>[Examples.tsx]"]
  node_header["Site navigation<br/>[SiteHeader.tsx]"]
  node_theme["Theme state<br/>[theme.ts]"]
  node_media["Viewport query<br/>[useMedia.ts]"]
  node_tiles["Surface tiles<br/>[SurfaceTiles.tsx]"]
end

subgraph group_demos["Product Examples"]
  node_videodemo["Video controls"]
  node_notification["Notification demo"]
  node_switch["Switch demo<br/>[GlassSwitch.tsx]"]
  node_slider["Slider demo<br/>[GlassSlider.tsx]"]
  node_contextmenu["Context menu demo"]
end

node_developer(("Application developer"))

node_developer -->|"imports API"| node_entry
node_entry -->|"exports"| node_glass
node_entry -->|"exports"| node_signals
node_entry -->|"exports"| node_interaction
node_glass -->|"uses maps"| node_displacement
node_glass -->|"reads motion"| node_signals
node_glass -->|"renders DOM"| node_material
node_glass -->|"routes media"| node_surface
node_material -->|"uses maps"| node_displacement
node_material -->|"reads motion"| node_signals
node_surface -->|"generates maps"| node_displacement
node_surface -->|"reads motion"| node_signals
node_surface -->|"draws lenses"| node_webgl
node_interaction -->|"uses values"| node_signals
node_siteapp -->|"selects view"| node_router
node_siteapp -->|"renders view"| node_playground
node_siteapp -->|"renders view"| node_examplesview
node_siteapp -->|"renders view"| node_docs
node_header -->|"navigates"| node_router
node_header -->|"checks viewport"| node_media
node_playground -->|"renders demo"| node_demo
node_playground -->|"renders controls"| node_controls
node_playground -->|"renders navigation"| node_header
node_playground -->|"uses palette"| node_theme
node_playground -->|"checks viewport"| node_media
node_docs -->|"demonstrates API"| node_entry
node_docs -->|"renders navigation"| node_header
node_docs -->|"navigates"| node_router
node_docs -->|"uses palette"| node_theme
node_docs -->|"checks viewport"| node_media
node_examplesview -->|"renders navigation"| node_header
node_examplesview -->|"uses palette"| node_theme
node_examplesview -->|"renders example"| node_videodemo
node_examplesview -->|"renders example"| node_notification
node_examplesview -->|"renders example"| node_switch
node_examplesview -->|"renders example"| node_slider
node_examplesview -->|"renders example"| node_contextmenu
node_examplesview -->|"renders tiles"| node_tiles

click node_entry "https://github.com/samasante/liquid-glass/blob/main/src/index.ts"
click node_glass "https://github.com/samasante/liquid-glass/blob/main/src/Glass.tsx"
click node_material "https://github.com/samasante/liquid-glass/blob/main/src/GlassMaterial.tsx"
click node_displacement "https://github.com/samasante/liquid-glass/blob/main/src/displacement.ts"
click node_signals "https://github.com/samasante/liquid-glass/blob/main/src/signal.ts"
click node_interaction "https://github.com/samasante/liquid-glass/blob/main/src/interaction.tsx"
click node_surface "https://github.com/samasante/liquid-glass/blob/main/src/GlassSurface.tsx"
click node_webgl "https://github.com/samasante/liquid-glass/blob/main/src/glassWebGL.ts"
click node_siteapp "https://github.com/samasante/liquid-glass/blob/main/site/src/main.tsx"
click node_router "https://github.com/samasante/liquid-glass/blob/main/site/src/router.ts"
click node_playground "https://github.com/samasante/liquid-glass/blob/main/site/src/views/Playground.tsx"
click node_demo "https://github.com/samasante/liquid-glass/blob/main/site/src/components/GlassDemo.tsx"
click node_controls "https://github.com/samasante/liquid-glass/blob/main/site/src/components/GlassControlPanel.tsx"
click node_docs "https://github.com/samasante/liquid-glass/blob/main/site/src/views/Docs.tsx"
click node_examplesview "https://github.com/samasante/liquid-glass/blob/main/site/src/views/Examples.tsx"
click node_header "https://github.com/samasante/liquid-glass/blob/main/site/src/components/SiteHeader.tsx"
click node_theme "https://github.com/samasante/liquid-glass/blob/main/site/src/theme.ts"
click node_media "https://github.com/samasante/liquid-glass/blob/main/site/src/useMedia.ts"
click node_videodemo "https://github.com/samasante/liquid-glass/blob/main/examples/GlassVideoControls.tsx"
click node_notification "https://github.com/samasante/liquid-glass/blob/main/examples/GlassNotification.tsx"
click node_switch "https://github.com/samasante/liquid-glass/blob/main/examples/GlassSwitch.tsx"
click node_slider "https://github.com/samasante/liquid-glass/blob/main/examples/GlassSlider.tsx"
click node_contextmenu "https://github.com/samasante/liquid-glass/blob/main/examples/GlassContextMenu.tsx"
click node_tiles "https://github.com/samasante/liquid-glass/blob/main/site/src/components/SurfaceTiles.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_glass,node_interaction toneBlue
class node_material,node_displacement,node_signals,node_surface,node_webgl toneAmber
class node_siteapp,node_router,node_playground,node_demo,node_controls,node_docs,node_examplesview,node_header,node_theme,node_media,node_tiles toneMint
class node_videodemo,node_notification,node_switch,node_slider,node_contextmenu toneRose
class node_developer toneIndigo
```

## Components

### React Lens API

- [Public exports](https://github.com/samasante/liquid-glass/blob/main/src/index.ts): `src/index.ts`
- [Glass component](https://github.com/samasante/liquid-glass/blob/main/src/Glass.tsx): `src/Glass.tsx`
- [Interaction utilities](https://github.com/samasante/liquid-glass/blob/main/src/interaction.tsx): `src/interaction.tsx`

### Refraction Engine

- [DOM material](https://github.com/samasante/liquid-glass/blob/main/src/GlassMaterial.tsx): `src/GlassMaterial.tsx`
- [Displacement maps](https://github.com/samasante/liquid-glass/blob/main/src/displacement.ts): `src/displacement.ts`
- [Motion values](https://github.com/samasante/liquid-glass/blob/main/src/signal.ts): `src/signal.ts`
- [WebGL surfaces](https://github.com/samasante/liquid-glass/blob/main/src/GlassSurface.tsx): `src/GlassSurface.tsx`
- [WebGL renderer](https://github.com/samasante/liquid-glass/blob/main/src/glassWebGL.ts): `src/glassWebGL.ts`

### Interactive Site

- [Site app router](https://github.com/samasante/liquid-glass/blob/main/site/src/main.tsx): `site/src/main.tsx`
- [View navigation](https://github.com/samasante/liquid-glass/blob/main/site/src/router.ts): `site/src/router.ts`
- [Playground view](https://github.com/samasante/liquid-glass/blob/main/site/src/views/Playground.tsx): `site/src/views/Playground.tsx`
- [Live glass demo](https://github.com/samasante/liquid-glass/blob/main/site/src/components/GlassDemo.tsx): `site/src/components/GlassDemo.tsx`
- [Optics controls](https://github.com/samasante/liquid-glass/blob/main/site/src/components/GlassControlPanel.tsx): `site/src/components/GlassControlPanel.tsx`
- [Documentation view](https://github.com/samasante/liquid-glass/blob/main/site/src/views/Docs.tsx): `site/src/views/Docs.tsx`
- [Examples gallery](https://github.com/samasante/liquid-glass/blob/main/site/src/views/Examples.tsx): `site/src/views/Examples.tsx`
- [Site navigation](https://github.com/samasante/liquid-glass/blob/main/site/src/components/SiteHeader.tsx): `site/src/components/SiteHeader.tsx`
- [Theme state](https://github.com/samasante/liquid-glass/blob/main/site/src/theme.ts): `site/src/theme.ts`
- [Viewport query](https://github.com/samasante/liquid-glass/blob/main/site/src/useMedia.ts): `site/src/useMedia.ts`
- [Surface tiles](https://github.com/samasante/liquid-glass/blob/main/site/src/components/SurfaceTiles.tsx): `site/src/components/SurfaceTiles.tsx`

### Product Examples

- [Video controls](https://github.com/samasante/liquid-glass/blob/main/examples/GlassVideoControls.tsx): `examples/GlassVideoControls.tsx`
- [Notification demo](https://github.com/samasante/liquid-glass/blob/main/examples/GlassNotification.tsx): `examples/GlassNotification.tsx`
- [Switch demo](https://github.com/samasante/liquid-glass/blob/main/examples/GlassSwitch.tsx): `examples/GlassSwitch.tsx`
- [Slider demo](https://github.com/samasante/liquid-glass/blob/main/examples/GlassSlider.tsx): `examples/GlassSlider.tsx`
- [Context menu demo](https://github.com/samasante/liquid-glass/blob/main/examples/GlassContextMenu.tsx): `examples/GlassContextMenu.tsx`

### Other components

- **Application developer**

## Connections

- Application developer → Public exports: imports API (evidence: `README.md`)
- Public exports → Glass component: exports (evidence: `src/index.ts`)
- Public exports → Motion values: exports (evidence: `src/index.ts`)
- Public exports → Interaction utilities: exports (evidence: `src/index.ts`)
- Glass component → Displacement maps: uses maps (evidence: `src/Glass.tsx`)
- Glass component → Motion values: reads motion (evidence: `src/Glass.tsx`)
- Glass component → DOM material: renders DOM (evidence: `src/Glass.tsx`)
- Glass component → WebGL surfaces: routes media (evidence: `src/Glass.tsx`)
- DOM material → Displacement maps: uses maps (evidence: `src/GlassMaterial.tsx`)
- DOM material → Motion values: reads motion (evidence: `src/GlassMaterial.tsx`)
- WebGL surfaces → Displacement maps: generates maps (evidence: `src/GlassSurface.tsx`)
- WebGL surfaces → Motion values: reads motion (evidence: `src/GlassSurface.tsx`)
- WebGL surfaces → WebGL renderer: draws lenses (evidence: `src/GlassSurface.tsx`)
- Interaction utilities → Motion values: uses values (evidence: `src/interaction.tsx`)
- Site app router → View navigation: selects view (evidence: `site/src/main.tsx`)
- Site app router → Playground view: renders view (evidence: `site/src/main.tsx`)
- Site app router → Examples gallery: renders view (evidence: `site/src/main.tsx`)
- Site app router → Documentation view: renders view (evidence: `site/src/main.tsx`)
- Site navigation → View navigation: navigates (evidence: `site/src/components/SiteHeader.tsx`)
- Site navigation → Viewport query: checks viewport (evidence: `site/src/components/SiteHeader.tsx`)
- Playground view → Live glass demo: renders demo (evidence: `site/src/views/Playground.tsx`)
- Playground view → Optics controls: renders controls (evidence: `site/src/views/Playground.tsx`)
- Playground view → Site navigation: renders navigation (evidence: `site/src/views/Playground.tsx`)
- Playground view → Theme state: uses palette (evidence: `site/src/views/Playground.tsx`)
- Playground view → Viewport query: checks viewport (evidence: `site/src/views/Playground.tsx`)
- Documentation view → Public exports: demonstrates API (evidence: `site/src/views/Docs.tsx`)
- Documentation view → Site navigation: renders navigation (evidence: `site/src/views/Docs.tsx`)
- Documentation view → View navigation: navigates (evidence: `site/src/views/Docs.tsx`)
- Documentation view → Theme state: uses palette (evidence: `site/src/views/Docs.tsx`)
- Documentation view → Viewport query: checks viewport (evidence: `site/src/views/Docs.tsx`)
- Examples gallery → Site navigation: renders navigation (evidence: `site/src/views/Examples.tsx`)
- Examples gallery → Theme state: uses palette (evidence: `site/src/views/Examples.tsx`)
- Examples gallery → Video controls: renders example (evidence: `site/src/views/Examples.tsx`)
- Examples gallery → Notification demo: renders example (evidence: `site/src/views/Examples.tsx`)
- Examples gallery → Switch demo: renders example (evidence: `site/src/views/Examples.tsx`)
- Examples gallery → Slider demo: renders example (evidence: `site/src/views/Examples.tsx`)
- Examples gallery → Context menu demo: renders example (evidence: `site/src/views/Examples.tsx`)
- Examples gallery → Surface tiles: renders tiles (evidence: `site/src/views/Examples.tsx`)