NIB / DOCUMENTATION
Liquid glass — NibComponents
Explore clear and depth water, merging drops and shared bubbles over a live Flutter subtree.
Open interactive viewMeet the Water Lab
Start with two drops over a neutral grid. Drag one toward the other, or use Merge drops. A connecting neck grows as the bodies approach. Once they join, their body identity remains joined after release. Make a wave disturbs the material; Split moves the regions apart again. Reset water restores the initial arrangement immediately.
The Droplets, Surface and Component scenes use NibWaterGlass from nib_components. It wraps NibWaterSurface from nib_motion. The engine receives an explicit background subtree, samples that subtree into an image, and uses a fragment shader to bend the sampled pixels. Foreground controls remain above the distortion.
This example uses the public water API available since nib_motion 0.3.5 and nib_components 0.2.3. It is a two-dimensional, physically informed visual model. It does not solve three-dimensional fluid flow or measure physical water volume. The legacy glass implementation remains available in the Material selector while the new direction is reviewed.
Build a small water surface
Import nib_components for NibWaterGlass and nib_motion for its controller, configuration and drop values. Declare both dependencies when you import both packages. The new APIs are in the local working candidate; version labels alone do not establish hosted availability. Use the candidate source and dependency instructions from the Water Lab report until publication is separately approved.
Give the scene a finite size. Coordinates and radii belong to that local box, in logical pixels. Create the controller once, pass it to one material surface, then dispose it when its owner leaves. The widget drives controller.advance through its ticker; do not drive the same controller from another ticker as well.
The small program below runs on its own. The full Copy example action includes the exact Water Lab implementation, selected settings, local artwork and theme. It copies the starting configuration, not the current wave frame or an arbitrary dragged position.
import 'package:flutter/material.dart';
import 'package:nib_components/nib_components.dart';
import 'package:nib_motion/nib_motion.dart';
void main() => runApp(const MaterialApp(home: WaterExample()));
class WaterExample extends StatefulWidget {
const WaterExample({super.key});
@override
State<WaterExample> createState() => _WaterExampleState();
}
class _WaterExampleState extends State<WaterExample> {
final water = NibWaterController(drops: const [
NibWaterDrop(id: 1, center: Offset(90, 130), radius: 48),
NibWaterDrop(id: 2, center: Offset(270, 130), radius: 48),
]);
@override
void dispose() {
water.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) => Scaffold(
body: SafeArea(child: Center(child: Column(
mainAxisSize: MainAxisSize.min,
children: [
SizedBox(width: 360, height: 260, child: NibWaterGlass(
controller: water,
surface: true,
animated: true,
sampling: NibWaterSampling.live,
background: const ColoredBox(
color: Color(0xFFECEBE5),
child: GridPaper(
color: Color(0xFF969B96), interval: 20,
divisions: 1, subdivisions: 1,
child: Center(child: Text('Look through the water',
style: TextStyle(color: Color(0xFF202724)))),
),
),
)),
TextButton(
onPressed: () => water.disturb(const Offset(180, 130)),
child: const Text('Make a wave'),
),
],
))),
);
}Understand what moves
The material contour is an implicit field built from participating drop regions. Nearby fields form a smooth connecting neck. The controller also records body membership, so visual contact has a lasting state rather than a brief bridge painted between two unrelated circles.
Disturbances are bounded radial impulses. Their fronts travel outward at waveSpeed; wavelength sets crest spacing and damping removes amplitude over elapsed seconds. Multiple impulses add together. The shader evaluates the resulting surface and uses its normal for refraction and light. A wave changes the background displacement instead of adding an unrelated ring on top.
Each source region contributes exp(-ln(2) × distance² / radius²), and the visible contour is the 0.5 level. Automatic coalescence requires a connecting neck above 0.52. The controller retains joined body identity after release. A deliberate split keeps automatic rejoining off until another drag begins or merge() is called.
The conserved proxy is the sum of pi × radius² for source regions. It describes two-dimensional source mass. The visible contour can change area during a merge, and the model does not claim exact silhouette-area or three-dimensional volume conservation. Body membership and the proxy can be inspected in Development details.
Merge without losing the source regions
NibWaterDrop has a stable integer id, a local center and radius, and an optional bodyId. Source regions remain identifiable after joining. They are material-editing handles, not application buttons whose meaning can be combined. A merged material must not imply that two independent application actions have merged.
merge() starts a controlled approach toward a joined arrangement. The phase progresses from separated through merging to merged. split() starts continuous separation and then returns to separated. Split is the deliberate way to break a merged body; releasing a pointer does not automatically split it. reset() instead restores the controller’s original drops.
Try Merge drops, then Split before the approach finishes. The next operation starts from the current arrangement. On a reduced-motion system the resulting state is available without the spatial transition. The preview’s buttons provide the same outcomes for keyboard users who cannot drag.
| API | Type | Default | Behavior |
|---|---|---|---|
| merge / split / reset | void Function() | explicit calls | Request joining, continuous separation, or immediate restoration of the initial arrangement. |
| phase | NibWaterPhase | separated | Read-only topology state: separated, merging, merged or splitting. |
| massProxy | double | sum of source pi × radius² | Two-dimensional source-area proxy in px²; not exact rendered contour area or fluid volume. |
Choose what the pointer should do
In Drag mode, a pointer takes ownership of a source region and moves the body. In Disturb mode, a tap injects an impulse and movement leaves a wake. These are separate modes so a gesture does not both displace a drop and scratch waves across it. Surface and Component scenes use Disturb; the pointer-mode inspector appears only for Droplets.
The public NibWaterSurface handles local pointer conversion, pointer-up and cancellation. For a custom interaction host, call beginDrag(pointer, localPosition), inspect its boolean result, then call dragTo for the same pointer id. Finish with endDrag; pass cancelled: true when the input is cancelled. cancelInputs releases all current ownership.
A body has one pointer owner at a time. Two separately owned bodies wait until a pointer is released before joining. A normal release preserves the current velocity and target. Cancellation freezes the owned body at its current centers and clears its velocity; it keeps any existing joined identity.
Use disturb(localPosition, strength: value) for an explicit impulse. Strength is an artistic height amplitude in logical pixels, not pressure from hardware. The example’s Make a wave button uses the center of the local scene. Ordinary mouse and touch coordinates are sufficient; this example does not use pressure.
| API | Type | Default | Behavior |
|---|---|---|---|
| interaction | NibWaterInteraction | disturb | disturb adds impulses; drag moves participating source regions. |
| disturb | void Function(Offset, {double? strength}) | config.impulseStrength | Adds a bounded local disturbance. Coordinates use the receiving surface’s logical pixels. |
| beginDrag / dragTo / endDrag | pointer id + local Offset | no input ownership | Explicit pointer ownership for a custom host. A pointer may update only its own acquired input. |
Tune one property at a time
NibWaterConfig controls the solver and legacy optics. NibWaterMaterial separates clear/depth optics and opt-in blur; NibWaterQuality controls device-relative input resolution. configure(nextConfig) changes parameters while retaining the current drops and active material state. An external controller owns its configuration; the NibWaterGlass config argument initializes only a widget-owned controller. This example configures its external controller when inspector settings change.
Begin with waveSpeed and damping. Higher speed moves fronts farther each second; higher damping removes waves sooner. Adjust wavelength for tighter or broader ripples. recovery changes how quickly shape targets are approached. These rates do not replace simulation time with an easing curve.
Configuration values are checked when a controller accepts them, including in release builds. The full API ranges are speed 0–1000 px/s, damping 0.25–12 /s, strength 0–24 px, wavelength 8–256 px, recovery 1–30 /s, refraction 0–48 and highlight 0–2. The inspector deliberately offers narrower ranges. Non-finite values and values outside the public bounds throw ArgumentError.
Use refraction and highlight last. Refraction is an artistic optical displacement strength; it is not the legacy refractiveIndex property. Highlight is light intensity. Neither is a substitute for meaningful geometry. Use the neutral grid and typography backgrounds to see whether the underlying pixels are actually displaced.
| API | Type | Default | Behavior |
|---|---|---|---|
| waveSpeed | double · px/s | 180 | Radial propagation speed; the inspector offers 40–400. |
| damping | double · /s | 2.4 | Wave amplitude decay rate; the inspector offers 0.3–8. |
| impulseStrength | double · artistic px | 5 | Default wave-height amplitude; the inspector offers 0–12. |
| wavelength | double · px | 46 | Crest spacing; the inspector offers 16–120. |
| recovery | double · /s | 14 | Shape-target recovery rate; the inspector offers 2–30. |
| refraction | double · artistic strength | 16 | Optical displacement strength; the inspector offers 0–40. Zero removes refraction. |
| highlight | double | 0.6 | Surface light intensity; the inspector offers 0–1. |
Provide the pixels behind the water
background is an explicit Flutter subtree. NibWaterSurface places it in a separate capture boundary. Water is excluded from that boundary, preventing the next frame from sampling the previous water effect. The background remains part of normal Flutter layout; no screen recording, WebView or website-only renderer is involved.
The lab selects live sampling: child layers are sampled during scene composition, including nested repaint boundaries. Static sampling caches input until backgroundChanges or a size/quality change. Throttled sampling caps input refresh at the configured interval (33 ms by default) while waves can keep moving. Legacy preserves the asynchronous snapshot path and may require explicit invalidation for independently composited changes.
The caller owns backgroundChanges. Retain the signal while the material uses it, and dispose an owned controller or notifier in its owner. The water widget subscribes and unsubscribes but does not dispose your signal. Do not assume that every independently composited animation is detected without this connection.
The Grid and Typography choices are deliberately neutral. The Image choice is original local vector artwork painted in the copied Dart source, with no remote service or licensing dependency. Scrolling contains real local content; Move background changes its scroll offset by 100 logical pixels, making capture updates easy to inspect.
Sampling is bounded to the designated scene. It is not a way to refract arbitrary content elsewhere in an application. A blank, uniform background gives the shader little detail to bend. Avoid adding strong tint or blur to conceal missing refraction; first read the active renderer path and test a grid.
| API | Type | Default | Behavior |
|---|---|---|---|
| background | Widget | required | Designated content sampled below the material. Must have finite constraints. |
| backgroundChanges | Listenable? | null | Caller-owned invalidation signal for independently composited background changes. Ordinary repaint and descendant scrolling are detected automatically. The widget manages its listener, not ownership of the signal. |
| child | Widget? | null | Sharp foreground above the water. Controls may also live in background; bounded distortion retains their original hit-test and semantic geometry. |
| surface | bool | false | False renders participating droplets. True fills the bounded scene with the same surface and optics. |
Put a real action above the material
The Component scene uses the same water renderer with surface: true. A NibButton saves a local note in the foreground. Its text, focus and pressed feedback remain separate from the sampled backdrop. This is an application composition, not a new payment service or an interaction inferred from the shape of a droplet.
Use child for sharp foreground content, and keep its contrast stable as the background changes. The preview uses a mostly opaque themed card behind the note so its readability does not depend on the lens. The water around it remains interactive.
NibWaterGlass can create and own a controller when none is passed. Use an external NibWaterController for deliberate merging, splitting, custom initial drops or diagnostic access. The external owner must dispose that controller; the material does not take ownership of it.
Own the controller and respect the clock
Create an external controller in State, retain it through ordinary rebuilds, and dispose it in State.dispose. Switching between drop/surface/component scenes retains state. Entering or leaving the emitter scene creates a fresh controller with explicit ownership. Config changes retain body membership. Emission can stop while existing bubbles finish; reduced motion freezes their current poses.
The renderer uses its ticker and controller activity to advance the model. It honors TickerMode, application lifecycle, its paused argument and the system reduced-motion preference. Resume handling bounds elapsed work instead of integrating an entire period spent in the background.
The controller accepts zero to ten source regions, with unique ids and radii from 8 to 256 logical pixels. It keeps at most twelve live impulses, replacing the oldest when the limit is reached. A wave expires below 0.01 amplitude or after eight active simulation seconds. An advance accepts at most 66ms and divides it into steps of at most 1/120 second; excess wall time is discarded.
The simulation controller accepts elapsed seconds through advance. Use that method directly for deterministic tests or a custom scheduler. Do not call it every frame from a second owner while a NibWaterSurface is already driving it. Simulation time and widget rebuilds are separate: the preview observes discrete phase changes instead of rebuilding the page for every wave.
| API | Type | Default | Behavior |
|---|---|---|---|
| animated | bool | false | NibWaterGlass enables evolving body and wave motion only when true. The Water Lab and runnable water example set true. NibWaterSurface itself has no animated property. |
| captureScale | double | 1 | Legacy policy only: 0.5–2 absolute pixels per logical pixel, capped at two million pixels. Candidate quality is separately device-relative. |
| paused | bool | false | Pauses the renderer’s simulation work; outer TickerMode and app lifecycle also apply. |
| reducedMotion | bool | false | Requests less spatial motion. The system preference takes priority. |
| configure | void Function(NibWaterConfig) | constructor config | Updates the controller configuration without recreating it. |
| dispose | void Function() | called by owner | Release an external controller when its owning scene leaves. |
Read the actual rendering path
Development details shows loading, refractive or fallback from NibWaterRenderStatus. A refractive status reports that the shader and sampled background were bound for this material. It does not certify physical-device rendering, GPU speed, or every browser backend.
The fallback keeps the content usable when the shader or capture path is unavailable. It is not equivalent to the refraction effect and does not pass the Water Lab’s visual review gate. Use the legacy Material choice for a separate comparison; do not label an unchanged legacy effect as the new water renderer.
Capture count and last capture duration describe background sampling. Last solver-step duration describes CPU simulation work. These numbers are not frame time, raster time or display frame rate. Browser/backend evidence and controlled measurements belong in the Water Lab implementation report.
| API | Type | Default | Behavior |
|---|---|---|---|
| onStatus | ValueChanged<NibWaterRenderStatus>? | null | Reports path, captureCount, lastCaptureMicros and a diagnostic message. |
| NibWaterRenderPath | enum | loading | loading, refractive or fallback. A successful binding is not a GPU performance guarantee. |
Keep the result available without dragging
Merge drops, Split, Make a wave and Reset water are real keyboard-focusable buttons. A person can reach the resulting state without a drag gesture. The decorative backdrop is not a second application control. Component-scene controls keep their ordinary semantics and focus even while the material shape changes.
Less motion requests a static or reduced-spatial result; the system preference always wins. Pause water freezes the simulation separately. Reset water restores initial material state and leaves pause and reduced-motion choices alone. The outer playground’s Pause and Reduce motion controls apply too.
Do not announce every solver frame. The example displays discrete phase changes as text and keeps capture/solver diagnostics inside a collapsible panel. Check focus order, contrast, text scaling and cancellation separately from physical touch and screen-reader testing.
Keep the legacy path during review
NibWaterGlass is added alongside NibLiquidGlass. Existing NibLiquidGlass consumers and the Liquid Glass route remain valid. Choose Material: legacy to inspect the original blur, rim, rounded/capsule shape and pointer lighting. Its optics use different properties and a different renderer path.
Do not mechanically map refractiveIndex, blurSigma or chromaticAberration onto NibWaterConfig. The new material samples an explicit local background and derives optics from its moving surface. Migrate a bounded scene, verify its pixels and interactions, then compare the result before changing production use.
Web review comes before Android validation. Native GPU appearance, physical touch and assistive-technology results must be recorded independently. Stable API status does not replace renderer, device or accessibility verification for the application using it.
Legacy glass: Start with a backdrop worth seeing
NibLiquidGlass is a container, not a button or a complete screen. Place it above content in a Stack. Its filter samples what has already been painted behind it; its child is painted afterward and stays sharp. A flat background hides most of the effect, so this example provides a grid and a small local notes scene.
Use it for a bounded floating control or a short information panel. Prefer an opaque NibCard when long-form text, contrast or a predictable fill matters more than seeing through the surface. Keep foreground text readable in both the shader and fallback paths.
NibLiquidGlass belongs to nib_components. It wraps NibGlass from nib_motion with pointer-driven lighting, optional press animation and content padding. These are two layers of the same effect, not two separate visual components in this catalog.
Legacy glass: Set up a bounded surface
Import package:nib_components/nib_components.dart for NibLiquidGlass and glassLightFromPointer. Import package:nib_motion/nib_motion.dart when you use NibGlass diagnostics or provide a NibTransition yourself. If your app imports nib_motion directly, declare it as a direct dependency as well.
This site runs the local nib_components 0.2.2 candidate with the local nib_motion 0.3.4 candidate. These version labels do not establish that the same candidate is published. The complete exported example includes its tested theme and configuration; resolve the package sources described by the export instructions.
Give the surface finite constraints. The example below fixes its scene and glass dimensions; in a responsive layout, cap the glass width from LayoutBuilder constraints. The shader asset is provided by nib_motion at packages/nib_motion/lib/shaders/liquid_glass.frag. A missing or unsupported shader uses the fallback.
import 'package:flutter/material.dart';
import 'package:nib_components/nib_components.dart';
class MinimalGlass extends StatelessWidget {
const MinimalGlass({super.key});
@override
Widget build(BuildContext context) {
final theme = NibTheme.of(context);
return SizedBox(
width: 320,
height: 220,
child: Stack(
alignment: Alignment.center,
children: [
Positioned.fill(
child: DecoratedBox(
decoration: BoxDecoration(
gradient: LinearGradient(
colors: [theme.background, theme.secondary, theme.primary],
),
),
),
),
NibLiquidGlass(
width: 260,
height: 140,
child: Text('Content stays sharp.',
style: TextStyle(color: theme.foreground)),
),
],
),
);
}
}Legacy glass: Separate pointer lighting from animation
With interactive: true, mouse hover and pointer movement aim the light toward the local pointer position. Pointer down sets the pressed state. Pointer up, cancellation and mouse exit reset the light and pressed state. Setting interactive: false clears an outstanding decorative press, restores the rest light and removes those pointer handlers; it does not disable a button or input inside child.
animated: true wraps the surface in NibMotion and changes its scale between 1.0 and 0.98 while pressed. Without that opt-in, there is no NibMotion wrapper and no press scale. Hover lighting still updates. transition is used only for this optional press animation; its default is a 140ms NibTransition.
Try holding the empty part of the glass, then releasing or cancelling the pointer. The event readout records actual pointer events observed by the example host. NibLiquidGlass itself exposes no onTap, onHover or onPressed callback. Pin note is a separate NibButton with its own real onPressed callback and local pinned state.
| API | Type | Default | Behavior |
|---|---|---|---|
| interactive | bool | true | Enables pointer lighting and press-state tracking. Child interactions are independent. |
| animated | bool | false | Adds NibMotion for scale feedback; false builds no NibMotion wrapper. |
| transition | NibTransition? | null | Optional press animation configuration. Null selects a 140ms transition when animated is true. |
| restLightDirection | Offset | Offset(-0.4, -1) | Direction restored on pointer release, cancellation or exit. It points toward the light. |
Legacy glass: Tune the surface before the optics
blurSigma is the Gaussian blur amount, not opacity. Start near the default 1 and increase it to make the backdrop less legible. tint is an optional Color painted over the backdrop; its alpha controls the wash. The component defaults to a subtle white tint based on Theme brightness: 0x0AFFFFFF in dark mode and 0x0DFFFFFF in light mode.
highlight sets rim-light intensity. showBorder adds a separate one-pixel white outline around the component content. Turning showBorder off does not turn highlight off and does not remove the engine’s painted rim. Compare those two controls separately.
The demo uses inherited NibTheme colors for the backdrop, foreground and button. The native glass tint and default 24px corner radius are not replaced by NibTheme.primary or radiusDefault. Pass tint or borderRadius explicitly when those defaults do not suit your app.
| API | Type | Default | Behavior |
|---|---|---|---|
| blurSigma | double | 1 | Backdrop blur on the shader and fallback paths. Use finite non-negative values. |
| tint | Color? | null | Null chooses the brightness-dependent white sheen; a supplied color is used directly. |
| highlight | double | 0.5 | Rim-light intensity. The documented range is 0..1. |
| showBorder | bool | true | Adds a separate outline; it does not disable the underlying rim light. |
Legacy glass: Know which controls need the shader
thickness, refractiveIndex, chromaticAberration and saturation are forwarded to the NibGlass shader. They are not implemented by the frosted fallback. The inspector keeps them available as advanced settings so the same exported configuration can be tried on a supported device; changing them in a fallback preview should not be described as a visual success.
thickness controls the edge band of the shader’s dome model in logical pixels. It does not add padding, change the widget’s layout thickness or make the whole surface uniformly distorted. refractiveIndex: 1.0 requests no bending. chromaticAberration: 0 disables the additional dispersion sampling. saturation: 1.0 preserves the sampled color saturation.
These are visual shader parameters, not a measurement of real material optics. The example bounds controls to useful finite ranges; the component constructor does not enforce those ranges with assertions. Do not pass NaN or infinite values.
| API | Type | Default | Behavior |
|---|---|---|---|
| thickness | double | 24 | Logical-pixel dome edge band. Shader only; NibGlass itself defaults to 20. |
| refractiveIndex | double | 1.2 | Shader refraction parameter; 1.0 means no bending. |
| chromaticAberration | double | 0.03 | Shader red/blue dispersion amount; zero disables the extra sampling. |
| saturation | double | 1.3 | Shader backdrop saturation factor; 1.0 leaves it unchanged. |
Legacy glass: Control size, padding and clipping
child is required. width and height are optional outer dimensions, and padding defaults to EdgeInsets.all(20) around the child. A custom clipper overrides borderRadius for clipping. Otherwise the default radius is 24px; keep radii uniform when testing the shader, whose radius uniform currently reads the top-left corner.
The Rounded and Capsule options in this example both use borderRadius. Capsule uses a radius equal to half the 188px glass height. Text and controls still need room inside the curved edges, so the example increases horizontal padding for that shape.
CustomClipper<Path> supports an arbitrary clipped outline, but the current shader does not accept the path as its refraction geometry. Its model remains a rounded rectangle. Test custom shapes in the intended renderer instead of assuming their lensing matches the clip. A custom clipper also removes the component’s rounded border radius from its extra outline.
| API | Type | Default | Behavior |
|---|---|---|---|
| child | Widget | required | Foreground content painted above the filtered backdrop. |
| width / height | double? | null / null | Optional dimensions. Finite parent constraints are needed for the shader path. |
| padding | EdgeInsetsGeometry | EdgeInsets.all(20) | Inset around the child. Supports directional padding. |
| borderRadius | BorderRadius? | null → 24px | Rounded clipping and outline shape when clipper is absent. |
| clipper | CustomClipper<Path>? | null | Overrides clipping shape. Does not provide arbitrary-path refraction geometry to the current shader. |
Legacy glass: Compute a light direction explicitly
glassLightFromPointer(Offset pointer, Size size) returns a unit Offset from the center of size toward a pointer in that box’s local coordinates. Pass localPosition, not a global screen position. It returns Offset(0, -1) for an empty or non-finite size, a centered pointer or a non-finite vector.
NibLiquidGlass already calls this helper for native pointer tracking. Use the helper yourself when building a custom composition directly with NibGlass. It is a pure function: there is no controller, subscription or disposal step.
final direction = glassLightFromPointer(
const Offset(180, 60),
const Size(240, 120),
); // Offset(1, 0): pointer is to the right of the center.| API | Type | Default | Behavior |
|---|---|---|---|
| glassLightFromPointer | Offset Function(Offset pointer, Size size) | no optional arguments | Returns a finite unit direction; falls back to Offset(0, -1) for degenerate input. |
Legacy glass: Read the renderer result honestly
NibGlass selects its shader path only after the program loads, shader image filters are supported, and layout supplies a finite non-empty size. Otherwise it paints a BackdropFilter blur, tint and directional rim. This browser preview reports the actual capability check instead of calling the fallback equivalent to refraction.
NibGlass.debugShaderPathAvailable() returns Future<bool>. It checks shader-filter support and whether the bundled liquid-glass program can load. It is useful for a diagnostic label; it does not confirm a particular frame’s geometry, GPU cost or physical-device appearance. A true result does not remove the bounded-layout requirement.
Expect the fallback on a browser/backend without shader-image-filter support. Shader loading is asynchronous, so the fallback can also appear temporarily on a supported renderer. Keep content usable through that transition; never make an essential control depend on a refraction effect.
| API | Type | Default | Behavior |
|---|---|---|---|
| NibGlass.debugShaderPathAvailable | static Future<bool> Function() | no arguments | Diagnostic in nib_motion. True requires shader-filter support and successful shader program loading. |
Legacy glass: Keep application state outside the material
NibLiquidGlass owns its transient light and press state. It exposes no controller and no disposal method. NibGlass loads the shared shader asynchronously and checks mounted before rebuilding after completion. Removing the widget releases its widget-owned animation state; keep expensive scenes bounded and mount only the preview the visitor requests.
This example owns one local pinned boolean. Changing blur, shape or backdrop does not remount the glass or reset that note. The external ComponentSettings object is the inspector configuration, not a package controller; onChanged publishes a new settings value to the host. Complete export includes this helper and the same configured values.
The demo’s event readout belongs to the host. Pointer events and the note button callback are real observations, not NibLiquidGlass callback properties. The patterned and content backdrops are local fixtures and make no network requests.
Legacy glass: Keep content usable without decorative motion
The glass container is decorative and does not become a semantic button. Put real controls inside child, with their own labels, focus and keyboard actions. The example’s Pin note uses NibButton; decorative backdrop text is excluded from semantics so it is not read as a second unrelated document.
The package’s NibMotion path respects its reduced-motion policy. Reduced motion removes the animated transition; press state can still change immediately. Keep the text and button fully usable with animated: false or interactive: false. Inspect contrast over every backdrop because blur and transparency do not guarantee it.
When testing, check pointer down/cancel/release, keyboard activation of the child, text scaling, narrow layouts and disposal during a press. A desktop pointer test is distinct from a physical touch or screen-reader run.
Legacy glass: Diagnose an effect that looks flat
No visible change from optics controls: read the renderer status first. Those parameters have no fallback implementation. If blur also seems absent, put a grid or text behind the surface and ensure the glass is painted above it in the same scene.
No press response: animated defaults to false and interactive must be true. Lighting can still move without scale. A child button can work while decorative interaction is off; that is expected. transition has no effect when animated is false.
Unexpected shape or clipping: check finite dimensions, content padding and whether clipper overrides borderRadius. Keep strong foreground contrast and test both renderer paths before relying on the effect in an application.
Limits and platform evidence
Water Lab uses the stable public water API. The refractive path must be checked in a real browser; fallback rendering does not satisfy visual review.
The model preserves source-region area as a 2D mass proxy. It does not conserve exact silhouette area or solve 3D fluid flow.
Capture is restricted to the designated bounded background. Platform views and content outside that subtree are not supported background inputs.
Android GPU, physical touch and screen-reader validation remain separate checks after maintainer web review.