Align docs with the component library

CONTRIBUTING.md

@@ -1,13 +1,13 @@
 # Contributing
 
-Use Node.js 24+, pnpm 10.33.2 and `pnpm install --frozen-lockfile`, then `pnpm dev` for the demo app. The landing page, playground, showcase and `/components` guide share one Next.js app. Run `pnpm check` before opening a pull request. Keep the library and demo responsibilities separate.
+Use Node.js 24+, pnpm 10.33.2 and `pnpm install --frozen-lockfile`, then `pnpm dev` for the demo app. The landing page, `/components` editor and showcase share one Next.js app. The former Playground is now the Liquid Glass tab under Components; old links redirect there. Run `pnpm check` before opening a pull request. Keep the library and demo responsibilities separate.
 
 The demo consumes the built workspace package through `workspace:*`. Its `dev`, `build` and `typecheck` scripts prepare the library's ignored `dist` exports before running Next.js, including from `apps/demo`. Rebuild with `pnpm --filter react-glaze build` after editing library source while the demo server is running.
 
 Use `pnpm pack:local` and an independent consumer that installs the resulting tarball to verify a new package build before release. That archive check verifies packaging separately from workspace development; see the [release procedure](docs/releasing.md).
 
 For optical changes, include a minimal reproduction and before/after browser evidence. Distinguish native Safari, Playwright WebKit, viewport emulation, Simulator and physical devices. Do not infer FPS from JavaScript submission timings.
 
-Preserve native element semantics, keyboard behavior, caller CSS and reduced-motion behavior. Document changes to the public API in `packages/react/README.md`, and add focused regressions for behavior changes. Generated output and local recordings do not belong in commits.
+Preserve native element semantics, keyboard behavior, caller CSS and reduced-motion behavior. Document changes to the public API in `packages/react/README.md` and the relevant guide in `docs/components.md`, and add focused regressions for behavior changes. Generated output and local recordings do not belong in commits.
 
 Report issues with browser/device versions, reproduction steps and the smallest useful example. Please do not include credentials or private page content.

README.md

@@ -2,7 +2,17 @@
 
 [Website](https://react-glaze.app/) · [Components](https://react-glaze.app/components) · [Liquid Glass editor](https://react-glaze.app/components?component=glass) · [Showcase](https://react-glaze.app/showcase) · [npm](https://www.npmjs.com/package/react-glaze)
 
-Liquid glass for React 19: a configurable wrapper, morphing menus, spring-driven actions and composable surfaces. Keep native content and your own CSS, and tune the material and motion.
+An open-source React 19 component library for liquid glass: a configurable wrapper, morphing menus, spring-driven actions and composable surfaces. Keep native content and your own CSS, and tune the material and motion.
+
+| Component | Use it for |
+| --- | --- |
+| `LiquidGlass` | Wrap existing buttons, cards and other native content in configurable glass |
+| `LiquidGlassActions` | Open separate action buttons in a row, column or fan |
+| `LiquidGlassMenu` | Morph a trigger into a menu panel |
+| `LiquidGlassGroup` | Coordinate the shared glass and motion of custom surfaces |
+| `LiquidGlassSurface` | Bind native content to a surface inside a group |
+
+Start with the three ready-made components, or compose your own interactions with the group and surface primitives. All five exports come from `react-glaze`.
 
 **Experimental.** Desktop Chrome, Firefox and Safari are the targets; iPhone Safari is experimental. Background capture is asynchronous and has [documented limitations](packages/react/README.md#known-limits).
 
@@ -37,7 +47,9 @@ No provider, background image prop or stylesheet import is required. Your conten
 
 ## Morphing components
 
-`LiquidGlassActions` opens a row, column or fan of native buttons. `LiquidGlassMenu` turns one trigger into a menu panel. Both use `LiquidGlassGroup` and `LiquidGlassSurface`, which are also available for building your own interactions. Adjust action size, signed trigger distance, refraction, exact duration and bounce independently.
+`LiquidGlassActions` opens a row, column or fan of native buttons. `LiquidGlassMenu` turns one trigger into a menu panel. Both use `LiquidGlassGroup` and `LiquidGlassSurface`, which are also available for building your own interactions. Adjust action size, signed trigger distance, connection reach, refraction, exact duration and bounce independently.
+
+The Components editor includes animation playback: pause, play, replay and scrub the actual spring animation, then tune the material on the held frame. Menu and group refs expose the same playback methods for your own tooling.
 
 [Component guide and examples](docs/components.md) · [Interactive components](https://react-glaze.app/components)
 

apps/demo/README.md

@@ -1,6 +1,6 @@
 # React Glaze demo
 
-One Next.js application for React Glaze, the experimental React 19 liquid glass wrapper. The landing pairs a quiet introduction with three original material scenes and a real draggable glass preview. Click the glass to switch between clear and frosted.
+One Next.js application for React Glaze, the experimental React 19 component library for liquid glass, morphing menus and composable surfaces. The landing pairs a quiet introduction with three original material scenes and a real draggable glass preview. Click the glass to switch between clear and frosted.
 
 ## Run from the workspace root
 
@@ -27,6 +27,8 @@ Use `pnpm pack:local` and an independently installed tarball consumer to verify
 
 The Liquid Glass editor retains the owner's exact initial/reset configuration. `/components` selects split actions by default; `component=actions|menu|glass` is addressable, and a `config` query without an explicit valid component selects the editor. Explicit `config` query parameters win over a manually saved local configuration. The storage key remains `react-glaze:playground:config:v1`. Save is manual, Reset does not overwrite the saved copy, Delete saved leaves the current preview intact, and uploaded image bytes are not stored. Storage belongs to an origin, so changing host or port does not transfer previous settings. Old `/?config=...` and `/playground` links redirect to `/components?component=glass` with their query values preserved.
 
+The two menu tabs expose the library's actual components and spring playback. Expand Animation playback to pause, play, replay or scrub the animation. Connection reach and refraction can be tuned while a menu is open or a frame is held. The editor associates its controls with the menu and uses its preview stage as the fitting boundary, so scrolling to a slider preserves the inspected state. The [component guide](../../docs/components.md) documents these APIs for consumers.
+
 Roam retains `liquid-showcase-trip-v1` for its local trip state. Photographs and fonts retain their [source attribution](ASSETS.md).
 
 ## Styling

docs/adoption.md

@@ -30,6 +30,8 @@ Use `LiquidGlass` to wrap existing content, `LiquidGlassActions` for separate ac
 
 ## Start with ordinary HTML and CSS
 
+The following examples cover the `LiquidGlass` wrapper. For action menus or custom groups, use the [component guide](components.md) alongside this introduction; those components expose their own geometry, motion and playback contracts.
+
 In a Next.js App Router page, a server component can render the library's client boundary directly:
 
 ```tsx
@@ -110,7 +112,7 @@ Updates remain asynchronous. A large capture root costs more than a small one, m
 
 ## Failure and lifecycle behavior
 
-Native HTML is server-rendered before the optical engine loads. `onReady` reports optical readiness, `onError` reports capture/render errors, and `onMetrics` provides throttled local counters. Errors hide the optical layer; original content remains. A successful refresh or WebGL context restoration can make it ready again.
+Native HTML is server-rendered before the optical engine loads. For `LiquidGlass`, `onReady` reports optical readiness, `onError` reports capture/render errors, and `onMetrics` provides throttled local counters. Errors hide the optical layer; original content remains. A successful refresh or WebGL context restoration can make it ready again. Morph groups have their own [lifecycle and playback callbacks](components.md); `onMetrics` belongs to the original wrapper.
 
 Hidden, offscreen and disabled surfaces pause. Final unmount releases observers, queues, source canvases, textures and the shared renderer. No idle animation loop is required. Data saving and reduced motion have their documented effects in the [package contract](../packages/react/README.md).