@glass-sdk/liquid-glass 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +596 -2
  3. package/dist/concentric-COCiG9DQ.js +179 -0
  4. package/dist/core.js +9 -0
  5. package/dist/dom-CKc8vDTR.js +2532 -0
  6. package/dist/dom.js +2 -0
  7. package/dist/gpu-Co5Y89mh.js +244 -0
  8. package/dist/gpu.js +2 -0
  9. package/dist/index.js +933 -0
  10. package/dist/map-encoder.worker-DO1drw0Y.js +16 -0
  11. package/dist/materials-DVPgteZ9.js +234 -0
  12. package/dist/styles.css +341 -0
  13. package/dist/styles.d.css.ts +2 -0
  14. package/dist/types/core/concentric.d.ts +32 -0
  15. package/dist/types/core/index.d.ts +10 -0
  16. package/dist/types/core/materials.d.ts +43 -0
  17. package/dist/types/core/morph-path.d.ts +110 -0
  18. package/dist/types/core/optics.d.ts +2 -0
  19. package/dist/types/core/progressive.d.ts +17 -0
  20. package/dist/types/core/shape.d.ts +16 -0
  21. package/dist/types/core/spring.d.ts +60 -0
  22. package/dist/types/core/union.d.ts +20 -0
  23. package/dist/types/dom/control-motion.d.ts +13 -0
  24. package/dist/types/dom/filter-bounds.d.ts +30 -0
  25. package/dist/types/dom/filter-patch.d.ts +9 -0
  26. package/dist/types/dom/fixed-shape.d.ts +3 -0
  27. package/dist/types/dom/foreground.d.ts +20 -0
  28. package/dist/types/dom/index.d.ts +61 -0
  29. package/dist/types/dom/interaction.d.ts +16 -0
  30. package/dist/types/dom/map-encoder.d.ts +5 -0
  31. package/dist/types/dom/map-encoder.worker.d.ts +1 -0
  32. package/dist/types/dom/map-encoding.d.ts +5 -0
  33. package/dist/types/dom/map-image.d.ts +14 -0
  34. package/dist/types/dom/map-store.d.ts +22 -0
  35. package/dist/types/dom/maps.d.ts +31 -0
  36. package/dist/types/dom/morph.d.ts +70 -0
  37. package/dist/types/dom/png.d.ts +7 -0
  38. package/dist/types/dom/progressive-maps.d.ts +6 -0
  39. package/dist/types/dom/progressive.d.ts +14 -0
  40. package/dist/types/dom/selection.d.ts +5 -0
  41. package/dist/types/dom/shape-layout.d.ts +29 -0
  42. package/dist/types/dom/ticker.d.ts +36 -0
  43. package/dist/types/dom/warm.d.ts +14 -0
  44. package/dist/types/gpu/index.d.ts +48 -0
  45. package/dist/types/index.d.ts +4 -0
  46. package/dist/types/react/control-thumb.d.ts +11 -0
  47. package/dist/types/react/index.d.ts +155 -0
  48. package/dist/types/react/merged-ref.d.ts +3 -0
  49. package/dist/types/react/shape.d.ts +23 -0
  50. package/dist/types/react/value-control-motion.d.ts +9 -0
  51. package/dist/types/react/value-controls.d.ts +20 -0
  52. package/package.json +80 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Glass HQ
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,597 @@
1
- # Temporary Holding Version
1
+ # Liquid Glass
2
2
 
3
- 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.
3
+ Clear and Regular glass materials for React, the web, and Electron. Built by [Glass](https://github.com/Glass-HQ) with **vgpu and WGSL**. MIT licensed.
4
+
5
+ [Interactive examples](https://liquid-glass.glassapp.dev/#examples)
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ bun add @glass-sdk/liquid-glass@~0.0.1
11
+ # npm install @glass-sdk/liquid-glass@~0.0.1
12
+ ```
13
+
14
+ The `~0.0.1` range accepts subsequent `0.0.x` patch releases.
15
+
16
+ ## Quick start
17
+
18
+ ```tsx
19
+ import {
20
+ GlassScene,
21
+ GlassContent,
22
+ GlassSurface,
23
+ GlassButton,
24
+ } from "@glass-sdk/liquid-glass";
25
+ import "@glass-sdk/liquid-glass/styles.css";
26
+
27
+ export function Example() {
28
+ return (
29
+ <GlassScene style={{ height: 400 }}>
30
+ <GlassContent>
31
+ <div
32
+ style={{
33
+ height: "100%",
34
+ background: "linear-gradient(120deg, #91b5c8, #d79872)",
35
+ }}
36
+ >
37
+ <h1>Your live content</h1>
38
+ </div>
39
+ </GlassContent>
40
+ <GlassSurface
41
+ material="regular"
42
+ radius={32}
43
+ style={{ position: "absolute", left: 40, top: 120, padding: 24 }}
44
+ >
45
+ <GlassButton onClick={() => console.log("Saved")}>Save</GlassButton>
46
+ </GlassSurface>
47
+ </GlassScene>
48
+ );
49
+ }
50
+ ```
51
+
52
+ `GlassContent` designates the live DOM content being refracted. Glass controls remain semantic HTML above it. The renderer follows the controls' real bounds, including translation, resize, and press animations. Ordinary text, SVG, and images remain live; the library never captures or screenshots the DOM.
53
+
54
+ ## Tint
55
+
56
+ Pass a six-digit hex color to any material component. Omit `tint` to restore
57
+ untinted glass. Tint gives the optical material a saturated hue, with refracted backdrop
58
+ luminance providing depth and color-aware highlights preserving the rim; it does not change the content color.
59
+
60
+ ```tsx
61
+ <GlassButton material="regular" tint="#007aff">Get started</GlassButton>
62
+ <GlassSurface material="clear" tint="#af52de">Your content</GlassSurface>
63
+ ```
64
+
65
+ The same prop is available on toolbars, tab lists and indicators, and menu or
66
+ submenu content. Set it on each material surface you want to color.
67
+
68
+ ## Motion
69
+
70
+ Glass responds to touch and pointer input the way the material does on iPhone.
71
+ Under a press it grows and lights up from beneath the pointer. Drag, and it
72
+ stretches toward your finger with constant volume, then settles with a gel-like
73
+ overshoot when you let go. Menus open as one continuous piece of glass: a
74
+ glass button becomes its menu, its icon withdrawing as the glass stretches
75
+ away from it and the items condensing out of a blur once there is room for
76
+ them; a button inside a toolbar lets the menu leave the toolbar as a drop,
77
+ joined by a liquid neck until it pinches off. Closing runs the same path back.
78
+ Toolbars flow when their spacers change, and the tab bar's selection lens
79
+ lifts so you can drag it to another tab.
80
+
81
+ Every component chooses sensible motion by default, and every glass surface
82
+ accepts the same props:
83
+
84
+ | Prop | Default | Meaning |
85
+ | ------------- | ---------------------- | ------- |
86
+ | `interactive` | See below | Grow under a press, stretch toward a drag, settle with overshoot, and light up beneath the pointer. |
87
+ | `morphFrom` | none | An element ref or getter. The surface grows out of that shape when it mounts, and shrinks back into it when a Base UI popup closes. |
88
+ | `morph` | by context | `"become"`: the source's glass is this surface, and its content withdraws while the surface is present. `"detach"`: the surface leaves the source's glass as a drop, joined by a liquid neck until they part. By default a glass source is become and a source inside glass, such as a toolbar button, is detached from. |
89
+ | `fluid` | `false` | Spring the glass outline when the surface's layout box changes. |
90
+ | `motion` | inherited | `"full"`, `"reduced"`, or `"none"`. Set it on `GlassScene` to apply it to every component. |
91
+
92
+ `GlassButton`, toolbars, and tab bars are interactive by default; pass
93
+ `interactive={false}` to keep one still. `GlassSurface` and menus are not,
94
+ because large surfaces usually hold content rather than act as a control. Menu
95
+ and submenu content always grows out of its trigger, and toolbar groups are
96
+ fluid.
97
+
98
+ ```tsx
99
+ // A draggable card that stretches with its own velocity.
100
+ <GlassSurface interactive radius={28} style={{ padding: 20 }}>…</GlassSurface>
101
+
102
+ // A custom popover that grows out of its trigger, using Base UI Popover.
103
+ // Portal popups into the scene so they refract the same content.
104
+ const scene = useRef<HTMLDivElement>(null);
105
+ const trigger = useRef<HTMLButtonElement>(null);
106
+ <GlassScene ref={scene}>
107
+ <GlassContent>…</GlassContent>
108
+ <Popover.Root>
109
+ <Popover.Trigger ref={trigger} render={<GlassButton />}>Share</Popover.Trigger>
110
+ <Popover.Portal container={scene}>
111
+ <Popover.Positioner sideOffset={8}>
112
+ <GlassSurface morphFrom={trigger} material="regular" radius={24}
113
+ render={<Popover.Popup />}>…</GlassSurface>
114
+ </Popover.Positioner>
115
+ </Popover.Portal>
116
+ </Popover.Root>
117
+ </GlassScene>
118
+ ```
119
+
120
+ Content inside a morphing surface is revealed as the glass opens rather than
121
+ scaled with it, condensing out of a blur once the outline has room for it, and
122
+ dissolving again as it closes. The glass itself never jumps between shapes:
123
+ the maps for the path are prepared as it is planned, and every frame blends
124
+ the two nearest. Exit animations work with any Base UI popup: the surface
125
+ keeps the popup mounted until the glass is back inside its source.
126
+
127
+ The system reduced-motion setting always applies, even with `motion="full"`:
128
+ elasticity, stretching, and travel are removed, and presentations fade in place.
129
+ The light under the pointer remains as a static cue. `motion="none"` removes
130
+ transitions entirely.
131
+
132
+ ## Components
133
+
134
+ | Export | Purpose |
135
+ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
136
+ | `GlassScene` | Owns content, surface registration, and filter composition. |
137
+ | `GlassContent` | The single live content layer to refract. |
138
+ | `GlassSurface` | A material surface, or a wrapper around your own component using `render`. |
139
+ | `GlassButton` | A semantic Base UI button with glass and focus/press behavior. |
140
+ | `GlassToolbar`, `GlassToolbarButton`, `GlassToolbarSpacer` | Toolbar with keyboard navigation, composable controls, and fixed or flexible spacing. |
141
+ | `GlassTabs` | Tabs with automatic selection, keyboard navigation, and a moving glass indicator. |
142
+ | `GlassMenu`, `GlassMenuTrigger`, `GlassMenuContent`, `GlassMenuItem` | Base UI menu primitives with a glass popup, keyboard navigation, and focus restoration. |
143
+
144
+ Compose your existing controls:
145
+
146
+ ```tsx
147
+ <GlassSurface material="clear" radius={28} render={<Button onClick={save} />}>
148
+ Save
149
+ </GlassSurface>
150
+
151
+ <GlassTabs material="regular" defaultValue="home"
152
+ items={[{ value: 'home', label: 'Home' }, { value: 'library', label: 'Library' }]}
153
+ aria-label="Navigation" />
154
+
155
+ <GlassMenu>
156
+ <GlassSurface render={<GlassMenuTrigger />}>Options</GlassSurface>
157
+ <GlassMenuContent material="regular">
158
+ <GlassMenuItem onClick={save}>Save</GlassMenuItem>
159
+ </GlassMenuContent>
160
+ </GlassMenu>
161
+ ```
162
+
163
+ `GlassTabs` manages selection by default; `defaultValue` chooses the initial tab (otherwise the first enabled item). Pass `value` and `onValueChange` only when your application needs to control selection.
164
+
165
+ Ordinary DOM placed above `GlassContent` can opt into foreground refraction with
166
+ `GlassForeground`. It adds no material or GPU maps. Slider and switch components
167
+ register their tracks and solid thumbs automatically; glass surfaces already
168
+ participate. Keep the foreground and the menus that overlap it in the same scene.
169
+
170
+ ```tsx
171
+ <GlassForeground render={<div className="floating-content" />}>
172
+ Text and controls that should refract beneath a glass menu
173
+ </GlassForeground>
174
+ ```
175
+
176
+ For an existing component ref, use `useGlassForeground()`; the DOM controller
177
+ provides `scene.addForeground(element)` and returns a cleanup function.
178
+
179
+ Set `material` and `appearance` on `GlassScene` to share defaults across its surfaces; individual components can override them. Menu popups default to Regular.
180
+
181
+ Every glass component must be inside `GlassScene`. Menu popups portal into that scene so their material uses the same content source. `render` components must forward their DOM ref. Use one `GlassContent` per scene. In Next.js, place interactive examples in a client component.
182
+
183
+ ## Composable tabs
184
+
185
+ `GlassTabs` is the convenient bar. For panels, custom triggers, disabled tabs,
186
+ vertical layouts, or application-controlled state, compose the same parts:
187
+
188
+ ```tsx
189
+ // Inside a GlassScene with a GlassContent layer:
190
+ <GlassTabsRoot defaultValue="preview">
191
+ <GlassTabsList aria-label="Component view">
192
+ <GlassTabsIndicator />
193
+ <GlassTabsTrigger value="preview">Preview</GlassTabsTrigger>
194
+ <GlassTabsTrigger value="usage">Install & Usage</GlassTabsTrigger>
195
+ </GlassTabsList>
196
+ <GlassTabsContent value="preview">Your preview</GlassTabsContent>
197
+ <GlassTabsContent value="usage">Your usage code</GlassTabsContent>
198
+ </GlassTabsRoot>
199
+ ```
200
+
201
+ All these parts are exported from `@glass-sdk/liquid-glass`. Root, trigger,
202
+ indicator, and panel preserve Base UI's native props, refs, and state callbacks.
203
+ The list adds material props and `size="sm"` or `size="lg"`. It can also sit inside an existing
204
+ Base UI/shadcn `Tabs` root; keep its `TabsContent` panels. Do not nest a second
205
+ root around the list. Use simple text/icons as tab labels, not interactive children.
206
+
207
+ ## Toolbar spacing and menus
208
+
209
+ Keep related controls together and separate actions into distinct glass
210
+ containers inside one semantic toolbar. `GlassToolbarSpacer` accepts `sizing="fixed"` for a standard gap or
211
+ `sizing="flexible"` (the default) to fill available space. Give the toolbar a
212
+ width or height when you want a flexible spacer to push controls apart.
213
+
214
+ Compose a menu trigger through the toolbar button's `render` prop:
215
+
216
+ ```tsx
217
+ // Inside a GlassScene with a GlassContent layer:
218
+ <GlassToolbar aria-label="Playback" style={{ width: 240 }}>
219
+ <GlassToolbarButton aria-label="Play" onClick={play}>▶</GlassToolbarButton>
220
+ <GlassToolbarButton aria-label="Volume" onClick={volume}>♪</GlassToolbarButton>
221
+ <GlassToolbarSpacer sizing="fixed" />
222
+ <GlassToolbarButton aria-label="Favorite">♡</GlassToolbarButton>
223
+ <GlassToolbarSpacer />
224
+ <GlassMenu>
225
+ <GlassToolbarButton aria-label="Playback options" render={<GlassMenuTrigger />}>
226
+ ⋯
227
+ </GlassToolbarButton>
228
+ <GlassMenuContent>
229
+ <GlassMenuItem onClick={save}>Save to library</GlassMenuItem>
230
+ <GlassMenuItem onClick={share}>Share</GlassMenuItem>
231
+ </GlassMenuContent>
232
+ </GlassMenu>
233
+ </GlassToolbar>
234
+ ```
235
+
236
+ All parts above are public exports. The trigger renders a single button and
237
+ participates in the toolbar's arrow-key navigation. Enter, Space, or the menu
238
+ opening arrow opens the menu; Escape closes it and restores trigger focus.
239
+ Menu state and callbacks stay on `GlassMenu`; positioning and material stay on
240
+ `GlassMenuContent`. Trigger-specific props can go on `GlassMenuTrigger`.
241
+
242
+ Spacers are decorative, never receive keyboard focus, and follow
243
+ `orientation="vertical"` automatically. The standard basis is 8px, in addition
244
+ to the toolbar's normal item gap. Override `--lg-toolbar-space` on the toolbar
245
+ or a spacer to change it. Each spacer ends the preceding glass container and
246
+ starts another after an uncovered gap. Place spacers as toolbar children;
247
+ arrays and fragments are supported. The example above creates three containers:
248
+ Play/Volume, Favorite, and the menu trigger. They share one keyboard navigation
249
+ scope. Material and radius apply to every container; layout styles apply to
250
+ the toolbar as a whole.
251
+
252
+ ## Defaults and customization
253
+
254
+ Import the SDK stylesheet once. It requires neither Tailwind nor a CSS reset.
255
+ Controls use compact defaults: `GlassButton` is 28px high with 8px horizontal
256
+ padding, 12px text, 500 weight, and a 4px gap. Button sizes `xs`, `sm`, and `lg`
257
+ are 20px, 24px, and 32px; the corresponding icon sizes are square. Toolbar
258
+ buttons default to 22px square inside a 3px inset, making the toolbar 28px high.
259
+ Use `size="default"` on `GlassToolbarButton` for text controls that fit their labels. Default tab bars are 32px high,
260
+ `sm` bars 28px, and `lg` bars 36px; tab labels retain weight 500 when selected.
261
+ Menus use a 4px inset, 128px minimum width, and 28px minimum-height rows.
262
+ Surfaces have no imposed width or height: application content sets their bounds.
263
+ Generic surface radius defaults to 8px. Buttons, toolbars, tab lists, and
264
+ indicators default to `radius="capsule"`; icon buttons use `"circle"`, and menu popups use 28px continuous corners.
265
+ Explicit material options can override them.
266
+
267
+ `GlassTabsIndicator` is the tab bar's selection lens, including when composed
268
+ with an existing Base UI tabs root. It springs between tabs, lifts and swells
269
+ under a press, stretches with its speed while dragged, and selects the tab it is
270
+ released over. Selection still belongs to the tabs: the lens activates a tab
271
+ exactly as a click would, so keyboard navigation and controlled state are
272
+ unchanged. `GlassTabs` uses the same part.
273
+ Material and appearance inherit from the scene; menus default to Regular.
274
+
275
+ The shipped CSS uses low-specificity `:where()` selectors. Override defaults with
276
+ `className`, inline styles, or your Tailwind utilities. For a custom radius, use
277
+ `radius` so the Lisse outline, content clip, and GPU optical field agree. Existing shadcn controls
278
+ keep their own styling; use a transparent background variant so their fill does
279
+ not hide the refracted layer.
280
+
281
+ `GlassSurface` uses Base UI `useRender`: element composition merges handlers,
282
+ classes, styles, and refs. Both the surface ref and rendered component ref are
283
+ preserved, including React 19 ref cleanup. A render function receives merged
284
+ props and must spread them onto its element. Custom components must forward
285
+ those props and the ref. `GlassButton` also accepts Base UI's `render` prop.
286
+
287
+ `GlassMenuContent` accepts `side` (`top`, `bottom`, `left`, `right`,
288
+ `inline-start`, or `inline-end`), `align` (`start`, `center`, or `end`),
289
+ `sideOffset`, `alignOffset`, and `collisionAvoidance` directly. Defaults are
290
+ `side="bottom"`, `align="end"`, and `sideOffset={8}`. Alignment works on all
291
+ sides. Base UI can flip or shift the popup to avoid viewport collisions.
292
+ Advanced `positionerProps` remain supported; direct positioning props take
293
+ precedence. `portalProps` accepts options such as `keepMounted`. The portal
294
+ stays inside the scene because its live optical source belongs there.
295
+
296
+ Compose submenus using Base UI behavior and the same glass content:
297
+
298
+ ```tsx
299
+ <GlassMenuContent side="top" align="center">
300
+ <GlassMenuItem onClick={save}>Save</GlassMenuItem>
301
+ <GlassMenuSubmenu>
302
+ <GlassMenuSubmenuTrigger>Share ›</GlassMenuSubmenuTrigger>
303
+ <GlassMenuSubmenuContent>
304
+ <GlassMenuItem onClick={copyLink}>Copy link</GlassMenuItem>
305
+ <GlassMenuItem onClick={email}>Email</GlassMenuItem>
306
+ </GlassMenuSubmenuContent>
307
+ </GlassMenuSubmenu>
308
+ </GlassMenuContent>
309
+ ```
310
+
311
+ Import `GlassMenuSubmenu`, `GlassMenuSubmenuTrigger`, and
312
+ `GlassMenuSubmenuContent` from the package root. Submenu content accepts the
313
+ same props as root content, defaulting to `side="inline-end"` and
314
+ `align="start"`. Nest these parts again for additional levels. Base UI owns
315
+ hover timing, arrow-key navigation, disabled items, and focus restoration.
316
+ There is no submenu enable flag: include the submenu parts when needed.
317
+ The same API works for a menu composed inside `GlassToolbar`; the toolbar
318
+ requires no separate submenu or positioning implementation.
319
+
320
+ Group, group label, separator, checkbox item, radio group, and radio item
321
+ exports use Base UI; add indicators for checked items as your application
322
+ requires. See the [Base UI menu reference](https://base-ui.com/react/components/menu)
323
+ for inherited props and event details.
324
+
325
+ Use `GlassToolbarButton`, `GlassToolbarLink`, and `GlassToolbarGroup` inside
326
+ `GlassToolbar` to participate in Base UI keyboard navigation. Toolbar buttons
327
+ use the same light/dark highlight as menu items on hover, keyboard focus, and
328
+ press. Use `aria-pressed` for toggle controls. Their highlights use circular icon buttons and continuous capsules for text buttons. Standalone `GlassButton` styling is independent.
329
+
330
+ ## Sliders and switches
331
+
332
+ ```tsx
333
+ import { GlassSlider, GlassSwitch } from "@glass-sdk/liquid-glass";
334
+
335
+ // Inside GlassScene, above GlassContent:
336
+ <GlassSlider aria-label="Volume" defaultValue={50}
337
+ onValueCommitted={(value) => console.log(value)} />
338
+ <GlassSlider ticks aria-label="Intensity" min={0} max={100}
339
+ step={25} defaultValue={50} />
340
+ <label>Notifications <GlassSwitch name="notifications" defaultChecked /></label>
341
+ ```
342
+
343
+ `GlassSlider` accepts a single numeric `value` or `defaultValue`, `min`, `max`,
344
+ `step`, `onValueChange`, and `onValueCommitted`. Defaults are 0–100 with a 0.1
345
+ step. Set `step={25}` and `ticks` for a stepped slider; the step must
346
+ divide the range evenly with at most 100 intervals. Both accept Base UI slider
347
+ root props, including `orientation`, `name` and `form`.
348
+ Use `aria-label` or `aria-labelledby` to name the input. `thumbProps` exposes
349
+ input refs, keyboard handlers and accessible value text.
350
+
351
+ `GlassSwitch` accepts Base UI switch props, including `checked` /
352
+ `defaultChecked`, `onCheckedChange`, `readOnly`, `required`, `name`,
353
+ `value`, `uncheckedValue` and `inputRef`. Name it with a wrapping label or
354
+ `aria-label`. `tint` sets the active track color on both controls; the thumbs
355
+ are solid white at rest. Pressing grows the thumb and reveals its glass lens,
356
+ which stretches with its speed while dragged; the switch thumb can be dragged
357
+ to either side and settles on release.
358
+ The pressed thumb defaults to clear glass; appearance inherits from the scene.
359
+ Refraction defaults to 5px for sliders and 7.75px for switches. Keyboard behavior, forms
360
+ and RTL come from Base UI. Both accept `motion` and `interactive`; reduced motion
361
+ disables thumb transitions.
362
+
363
+ ## Content shapes
364
+
365
+ Use `GlassShape` for images, cards, and content that needs continuous corners without a glass material. It uses Lisse and supports `radius` and `render` composition without requiring a `GlassScene`.
366
+
367
+ ```tsx
368
+ import { GlassShape } from "@glass-sdk/liquid-glass";
369
+
370
+ <GlassShape radius={14} render={<img src="/cover.jpg" alt="Album cover" />} />
371
+ <GlassShape radius="capsule" style={{ padding: "6px 14px" }}>Label</GlassShape>
372
+ ```
373
+
374
+ Clipping follows resizing automatically. Lisse renders content borders and shadows. Keep popups outside clipped content (the supplied menus use portals), and use inset focus indicators. Shapes wait for measurement rather than displaying a CSS-rounded substitute. Use `"circle"` on square elements. Numeric radii produce continuous rectangles; coordinate nested radii with their insets.
375
+
376
+ ## Props
377
+
378
+ | Prop | Default | Meaning |
379
+ | ------------ | ------- | ----------------------------------------------------------------------------- |
380
+ | `material` | `clear` | `clear` or `regular`; Regular adds frosting and a calibrated tone curve. |
381
+ | `appearance` | `light` | Explicit `light` or `dark` material calibration. |
382
+ | `radius` | `8` | Lisse continuous corner radius in CSS pixels, or `"capsule"` / `"circle"`. |
383
+ | `refraction` | `60` | Nonnegative displacement strength in CSS pixels. |
384
+ | `tint` | none | Optional six-digit hex tint, e.g. `#a8b8ff`. |
385
+
386
+ Both materials provide neutral foreground colors for their appearance. Override
387
+ `--lg-foreground` to customize text and icons. Clear preserves backdrop detail
388
+ with a compressed tonal range; Regular adds frosting. Nested surfaces limit
389
+ default refraction to their inset inside the parent, preventing a second lens
390
+ from pulling the parent's edge into its interior. An explicit `refraction`
391
+ overrides that limit. Tabs keep label weight stable while the selection lens moves.
392
+
393
+ `GlassScene` accepts `maxSurfaces` (default 16, maximum 64) and `onDiagnostic`. Diagnostics report registered/ready maps, map render plus readback time, and GPU errors. Time is map construction time, **not** FPS or continuous GPU frame time. Separate bounded scenes are preferable to filtering an entire long page.
394
+
395
+ ## Without React
396
+
397
+ ```ts
398
+ import { createGlassScene } from "@glass-sdk/liquid-glass/dom";
399
+ import "@glass-sdk/liquid-glass/styles.css";
400
+
401
+ const scene = createGlassScene(document.querySelector(".lg-scene")!);
402
+ scene.setContent(document.querySelector(".lg-content")!);
403
+ const remove = scene.addSurface(document.querySelector(".lg-surface")!, {
404
+ material: "regular",
405
+ radius: 32,
406
+ interactive: true,
407
+ });
408
+ // On teardown:
409
+ remove();
410
+ scene.dispose();
411
+ ```
412
+
413
+ Use the same positioned scene/content/surface structure as the React example. The DOM controller wraps the original source nodes in its filter passes and restores them on disposal. `/core` exposes material definitions and numerical optics; `/gpu` exposes `MaterialRenderer`, `getMaterialRenderer`, and `disposeMaterialRenderer`. `/dom` also exposes `getMaterialMaps` and `clearMaterialMapCache` for tools and diagnostics.
414
+
415
+ `addSurface` accepts the motion options above, with `morphFrom` as a getter.
416
+ `scene.addAnimator(animator)` steps your own animation each frame before the
417
+ scene measures glass, so geometry you write is refracted in the same frame.
418
+ `attachInteraction`, `attachGeometryMotion`, and `attachSelectionLens` are the
419
+ animators the components use. `/core` exports `Spring`, the shared `springs`,
420
+ and `rubberBand`.
421
+
422
+ ## How it works
423
+
424
+ vgpu renders WGSL material maps for displacement, coverage, highlights, and outline. Normal SVG filters apply them to the live content in `GlassContent`. Surfaces use their actual DOM bounds; content stays live without cloning or capturing it.
425
+
426
+ Maps are cached by geometry, display scale, and appearance. Moving or pressing a surface reuses its maps; resizing generates new ones. Every map requested in the same task is drawn into one atlas by a single precompiled pipeline and read back once; the pixels are encoded to PNG on a worker, never through a canvas, so the GPU process stays free for compositing. Encoded maps persist in IndexedDB, and the ones a page needed first are also kept in localStorage, so a reload composes its glass in the first frame that measures a surface, without touching the GPU. When glass changes shape in an animation, its springs are simulated ahead and the maps for the path are requested together as it starts. Content is clipped to exactly the shape being shown. A surface joined to other glass by a liquid neck draws their smooth union, traced from signed distances and rendered by the same WGSL field. Nested surfaces compose in DOM order.
427
+
428
+ Each surface's filter reads only realized images: the live source, edge tiles for the sides it samples past, its map images, and the finished layers of glass it overlaps. Glass merely near another surface takes that surface's rim and light images instead of its full layer, so no blur or displacement is ever evaluated twice. Scenes measure geometry only when something can change: input, scroll, resize, DOM mutation, CSS transitions, or a running spring. All scenes on a page share one animation frame, reading before any of them writes. Scene disposal removes filters and registrations.
429
+
430
+ Glass scenes allow controls and menus to extend beyond their layout bounds. Refraction repeats the nearest backdrop edge when sampling outside the supplied content. Clip images or other backdrop children when needed; clipping the scene itself also clips its controls and popups.
431
+
432
+ Use bounded scenes. Pixel density is capped at 2, and each atlas plane is limited to 4096 × 2048 pixels. `maxSurfaces` defaults to 16 and accepts at most 64.
433
+
434
+ ## Requirements
435
+
436
+ React 19+ is required for the React components. WebGPU requires an available adapter and HTTPS or localhost. Unsupported adapters report an error.
437
+
438
+ The content layer supports live text, SVG, and images. Arbitrary page-backdrop sampling, native video composition, transformed ancestors, and native/React Native ports are outside the supported scope. Cross-origin image/filter policies still apply. For NodeNext TypeScript projects, use `skipLibCheck: true` for the current upstream vgpu declarations.
439
+
440
+ ## Contributing
441
+
442
+ See the [development guide](https://github.com/Glass-HQ/liquid-glass/blob/main/CONTRIBUTING.md) for workspace setup, build commands, and verification.
443
+
444
+ ## Accessibility
445
+
446
+ Buttons, tabs, and menus use Base UI keyboard and focus behavior. Space and
447
+ Enter press interactive glass just as a pointer does. Motion is never the only
448
+ feedback: pressed, selected, and open states keep their highlight, and the
449
+ system reduced-motion setting removes elasticity and travel.
450
+
451
+ ## License
452
+
453
+ [MIT](./LICENSE).
454
+
455
+ ## Progressive blur
456
+
457
+ Soften live content progressively at an edge. Put the content to be blurred in
458
+ `GlassContent`; place captions and controls beside it to keep them sharp.
459
+
460
+ ```tsx
461
+ import { GlassScene, GlassContent, GlassProgressiveBlur } from "@glass-sdk/liquid-glass";
462
+ import "@glass-sdk/liquid-glass/styles.css";
463
+
464
+ <GlassScene style={{ height: 360, overflow: "hidden", borderRadius: 16 }}>
465
+ <GlassContent>
466
+ <img src="/landscape.jpg" alt="Mountain lake"
467
+ style={{ width: "100%", height: "100%", objectFit: "cover" }} />
468
+ </GlassContent>
469
+ <GlassProgressiveBlur edge="bottom" size={140} blur={24} />
470
+ <p style={{ position: "absolute", bottom: 24, left: 24 }}>A quieter place.</p>
471
+ </GlassScene>
472
+ ```
473
+
474
+ For a scroll container, `GlassScrollEdges` filters only the target scrollport. The blur stays anchored while its content scrolls, including during fast native scrolling. It does
475
+ not create scrollbars or change wheel, touch, or keyboard scrolling.
476
+
477
+ ```tsx
478
+ import { useRef, type ReactNode } from "react";
479
+ import { GlassScene, GlassContent, GlassScrollEdges } from "@glass-sdk/liquid-glass";
480
+
481
+ function ReadingList({ children }: { children: ReactNode }) {
482
+ const viewport = useRef<HTMLDivElement>(null);
483
+ return (
484
+ <GlassScene style={{ height: 360, overflow: "hidden" }}>
485
+ <div ref={viewport} tabIndex={0} role="region" aria-label="Reading list"
486
+ style={{ height: "100%", overflow: "auto", scrollPaddingBlock: 80 }}>
487
+ <GlassContent layout="flow">{children}</GlassContent>
488
+ </div>
489
+ <GlassScrollEdges target={viewport} size={80} blur={20} />
490
+ </GlassScene>
491
+ );
492
+ }
493
+ ```
494
+
495
+ Give the target an explicit height and `overflow: "auto"` or `"scroll"`. No extra filter wrapper is required: the SDK never applies the scroll-edge filter to the target's parent. Floating headers, footers, and navigation must be siblings outside the target to remain sharp. To refract the already-blurred content through a floating glass surface, put the scrollport inside a stationary `GlassContent` layer and the surface alongside that layer in the same `GlassScene`. Place headers and footers inside the target only when they should scroll and blur with its content. With a third-party ScrollArea,
496
+ pass a ref to its actual scrolling viewport. Use `edges={["inline-start",
497
+ "inline-end"]}` for a horizontal gallery; logical edges follow `direction` in
498
+ horizontal writing modes. `GlassContent layout="flow"` participates in normal
499
+ layout; the default `overlay` layout fills the scene for image backdrops.
500
+
501
+ | Prop | Default | Meaning |
502
+ | --- | --- | --- |
503
+ | `edge` | `"bottom"` | Primitive's strongest edge: `top`, `bottom`, `inline-start`, `inline-end`. |
504
+ | `edges` | `["top", "bottom"]` | Scroll helper's edges. Duplicate entries are ignored. |
505
+ | `target` | Required on scroll helper | An element ref to the scroll viewport. |
506
+ | `size` | `80` | Depth in CSS pixels, from 0 to 4096. Scroll edges clamp to half the viewport. |
507
+ | `blur` | `20` | Maximum Gaussian standard deviation in CSS pixels, from 0 to 64. |
508
+ | `refraction` | `0` | Optional optical travel in CSS pixels, from 0 to 32. |
509
+ | `disabled` | `false` | Remove the effect without changing the content. |
510
+
511
+ The primitive accepts standard div styling and refs, but no children. Size sets
512
+ its default depth; CSS can override the region's geometry. The helper renders no
513
+ element. A scene supports up to 64 progressive regions. Opposite scroll edges do
514
+ not overlap; perpendicular or custom overlapping regions compose in registration
515
+ order, so their blur can accumulate.
516
+
517
+ Reached scroll edges clear smoothly over the nearest 32 pixels (or the edge depth
518
+ when smaller). No overflow means no blur. Native content remains selectable and
519
+ accessible. Set scroll padding on your scroll viewport so keyboard-focused items
520
+ can be brought into its clear center. The effect disables itself for reduced
521
+ transparency and forced colors. When WebGPU cannot prepare maps, content stays
522
+ readable and `GlassScene.onDiagnostic` receives the error.
523
+
524
+ This is a smooth, seven-level approximation of spatially varying Gaussian blur,
525
+ using WGSL-generated weights and ordinary SVG filters on the explicit DOM layer.
526
+ It does not capture DOM into a texture. Content outside `GlassContent`, including
527
+ unrelated page layers, is not sampled. Keep fixed/sticky foreground controls outside
528
+ that filtered layer; filtering creates a containing block for positioned descendants.
529
+
530
+ ### Container-relative geometry
531
+
532
+ `GlassSurface` and fixed `GlassShape` elements declare their shape to descendants.
533
+ `GlassShape concentric` follows an inward offset of the nearest declared container
534
+ at the child's actual position. When `inset` is omitted, the smallest measured
535
+ edge inset is used, so changing container padding updates the relationship. Its `radius` controls the child's independent
536
+ corners where they do not meet the container boundary. Menu items and tab interaction
537
+ backgrounds use this automatically; first, middle, and last menu rows do not share
538
+ one hard-coded corner radius. Menu content clearance is shared across rows to keep
539
+ icons and labels aligned.
540
+
541
+ ```tsx
542
+ <GlassShape radius={40} style={{ padding: 4 }}>
543
+ <GlassShape concentric={{ inset: 4, contentPadding: 8 }} radius={8}>
544
+ Container-relative content
545
+ </GlassShape>
546
+ </GlassShape>
547
+ ```
548
+
549
+ Use `GlassShapeContainer` to declare geometry without clipping a layout containing
550
+ both content and overlays. Use `GlassCorner` for fixed-size controls near curved
551
+ corners. It positions the entire control with the requested clearance; it does not
552
+ change a circular control into a rounded rectangle.
553
+
554
+ ```tsx
555
+ <GlassShapeContainer radius={48} style={{ position: "relative", height: 320 }}>
556
+ <GlassCorner corner="top-right" gap={12} radius="circle">
557
+ <GlassShape radius="circle" render={<button aria-label="More" style={{ width: 32, height: 32 }} />}>…</GlassShape>
558
+ </GlassCorner>
559
+ </GlassShapeContainer>
560
+ ```
561
+
562
+ Both concentric shapes and corner controls accept `container={containerRef}` for
563
+ siblings or portals. Without that prop they use the nearest declared DOM ancestor.
564
+ The container must exist and have measurable dimensions. `GlassCorner` supports
565
+ `top-left`, `top-right`, `bottom-left`, and `bottom-right`; `enabled={false}` releases
566
+ its positioning. Its control must fit inside the container at the requested gap.
567
+ Layout tracks resizing, scrolling, and axis-aligned translation/scaling. Rotated
568
+ containers are not supported. Ordinary children retain their authored layout;
569
+ container declarations do not silently reposition unrelated content.
570
+
571
+ The `./dom` entry exports `registerShapeContainer`, `observeConcentricShape`, and
572
+ `observeCornerPlacement` for non-React integrations. Each returns a cleanup function.
573
+ Observers accept an optional container getter. The `./core` entry exports the same
574
+ geometry calculations (`insetShape`, `concentricOutline`, `cornerPlacement`) for
575
+ custom layout integrations. The inset is computed from a tessellated Lisse outline,
576
+ with the same corner smoothing used by the renderer; it is not radius subtraction.
577
+
578
+ Keep circular controls and intentional expanding thumb animations circular. Slider
579
+ and switch tracks retain their capsule layout; a pressed thumb may intentionally
580
+ grow outside the track. Use container-relative clipping for nested content and
581
+ interaction backgrounds, and corner placement for controls that must keep their
582
+ own shape.
583
+
584
+ `GlassSurface concentric` also resolves the glass material itself against the
585
+ nearest declared container. Its DOM contour, GPU coverage, refraction normals, and
586
+ edge lighting all use the same resolved outline. The selected tab indicator uses
587
+ this mode by default. Plain-DOM consumers can pass `concentric: { inset: 4 }` to
588
+ `controller.addSurface(element, options)`; registered surfaces declare their
589
+ container geometry automatically.
590
+
591
+ ```tsx
592
+ <GlassSurface radius={40} style={{ padding: 4 }}>
593
+ <GlassSurface concentric={{ inset: 4 }} radius={8}>
594
+ Nested glass
595
+ </GlassSurface>
596
+ </GlassSurface>
597
+ ```