@aberhamm/liquid-glass-react 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1191 @@
+import { ButtonHTMLAttributes } from 'react';
+import { CSSProperties } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { HTMLAttributes } from 'react';
+import { MouseEventHandler } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+import { RefObject } from 'react';
+
+/**
+ * Build a complete {@link BackdropSample} from an RGB backdrop estimate.
+ *
+ * @param color - The estimated backdrop color.
+ * @returns A `sampled: true` result with luminance + scheme filled in.
+ */
+export declare function averageColorToSample(color: Rgb): BackdropSample;
+
+/**
+ * The single result contract shared by every sampling strategy and surfaced by
+ * `useBackdropLuminance`.
+ */
+export declare interface BackdropSample {
+    /**
+     * Estimated relative luminance of the backdrop, normalized to `[0, 1]`, or
+     * `null` when sampling did not run or could not produce a value (SSR, no
+     * window, a tainted canvas, no element under the point).
+     */
+    luminance: number | null;
+    /**
+     * Coarse verdict derived from {@link BackdropSample.luminance} at
+     * {@link LIGHT_DARK_THRESHOLD}, or `null` when unsampled.
+     */
+    scheme: BackdropScheme | null;
+    /** `true` only when a real luminance reading was produced this call. */
+    sampled: boolean;
+}
+
+/** A coarse light/dark classification of a backdrop. */
+export declare type BackdropScheme = 'light' | 'dark';
+
+/**
+ * Directional scale (stretch) toward the cursor.
+ *
+ * The cursor offset `(mouse - center)` is normalized to a unit direction
+ * `(nx, ny)`. The stretch magnitude is
+ * `min(centerDist / 300, 1) * elasticity * fadeIn`. The element grows along the
+ * dominant axis and narrows along the other:
+ *
+ * ```text
+ * scaleX = 1 + |nx| * stretch * 0.3 - |ny| * stretch * 0.15
+ * scaleY = 1 + |ny| * stretch * 0.3 - |nx| * stretch * 0.15
+ * ```
+ *
+ * Both factors are clamped to `>= 0.8`. When `elasticity` is `0` (or the cursor
+ * is exactly on center) the result is the identity `{ scaleX: 1, scaleY: 1 }`.
+ *
+ * @param mouseX - Cursor X in the same coordinate space as `centerX`.
+ * @param mouseY - Cursor Y in the same coordinate space as `centerY`.
+ * @param centerX - Element center X.
+ * @param centerY - Element center Y.
+ * @param elasticity - Elastic strength; `0` disables motion entirely.
+ */
+export declare function calculateDirectionalScale(mouseX: number, mouseY: number, centerX: number, centerY: number, elasticity: number): DirectionalScale;
+
+/**
+ * Elastic positional nudge toward the cursor.
+ *
+ * Translates by `(mouse - center) * elasticity * 0.1 * fadeIn`, where `fadeIn`
+ * is the same activation ramp used by {@link calculateDirectionalScale}. When
+ * `elasticity` is `0` (or the cursor is on center / out of range) the result is
+ * `{ x: 0, y: 0 }`.
+ *
+ * @param mouseX - Cursor X in the same coordinate space as `centerX`.
+ * @param mouseY - Cursor Y in the same coordinate space as `centerY`.
+ * @param centerX - Element center X.
+ * @param centerY - Element center Y.
+ * @param elasticity - Elastic strength; `0` disables motion entirely.
+ */
+export declare function calculateElasticTranslation(mouseX: number, mouseY: number, centerX: number, centerY: number, elasticity: number): ElasticTranslation;
+
+/**
+ * Build a canvas-snapshot strategy from a caller-supplied painter.
+ *
+ * The library does NOT bundle an HTML-to-canvas renderer (zero new deps). A
+ * consumer that wants pixel-accurate sampling passes a `draw` callback that
+ * paints the backdrop region into the provided `CanvasRenderingContext2D`; this
+ * helper then averages the pixels and returns a {@link BackdropSample}. If the
+ * canvas is tainted by cross-origin content, `getImageData` throws
+ * `SecurityError` — which {@link safeSample} (or the hook) converts to
+ * {@link UNSAMPLED}. This helper does NOT swallow the error itself, so the
+ * single taint-handling boundary stays in {@link safeSample}.
+ *
+ * @param draw - Paints the backdrop into the 2D context for the given size.
+ * @returns A {@link SamplingStrategy} that averages the painted pixels.
+ */
+export declare function createCanvasSnapshotStrategy(draw: (ctx: CanvasRenderingContext2D, width: number, height: number) => void, size?: number): SamplingStrategy;
+
+/**
+ * Detect the current browser's liquid-glass capabilities.
+ *
+ * Safe to call during SSR: returns conservative all-`false` defaults when
+ * browser globals are unavailable, and never throws.
+ */
+export declare function detectGlassCapabilities(): GlassCapabilities;
+
+/**
+ * Pure elastic-motion math for `<LiquidGlass>` (plan 005).
+ *
+ * Two deterministic, side-effect-free functions translate a pointer position
+ * (relative to an element's center) into a CSS `transform`:
+ *
+ * - {@link calculateDirectionalScale} — a directional stretch (the glass bulges
+ *   toward the cursor, narrows across the perpendicular axis).
+ * - {@link calculateElasticTranslation} — a subtle positional nudge toward the
+ *   cursor.
+ *
+ * Both share the same activation model: a `fadeIn` ramp that grows as the cursor
+ * nears the element, a `stretch` magnitude that scales with distance from center
+ * and `elasticity`, and a hard `elasticity === 0 ⇒ no motion` guarantee. The
+ * component and the unit tests both consume these exact signatures.
+ */
+/** Result of {@link calculateDirectionalScale}. */
+export declare interface DirectionalScale {
+    /** Horizontal scale factor (`1` = unscaled), clamped `>= 0.8`. */
+    scaleX: number;
+    /** Vertical scale factor (`1` = unscaled), clamped `>= 0.8`. */
+    scaleY: number;
+}
+
+/**
+ * The displacement/refraction algorithm used to generate the SVG
+ * `feDisplacementMap` and tune the glass distortion.
+ *
+ * - `standard` — balanced edge-weighted displacement (the default look).
+ * - `polar` — radial/polar displacement, stronger toward the perimeter.
+ * - `prominent` — exaggerated displacement for a heavier "thick glass" feel.
+ * - `shader` — shader-style displacement profile for sharper highlights.
+ * - `turbulence` — adds fractal turbulence for an organic, watery distortion.
+ *
+ * @defaultValue `'standard'`
+ */
+export declare type DisplacementMode = 'standard' | 'polar' | 'prominent' | 'shader' | 'turbulence';
+
+/**
+ * The default, canvas-free sampling strategy.
+ *
+ * Walks the elements stacked under `point` (front-to-back via
+ * `document.elementsFromPoint`), reads each one's computed `background-color`,
+ * and composites them over an assumed-white page base. If an element carries an
+ * opaque `background-image` (e.g. a photo or gradient), its real pixel color is
+ * unknown to CSSOM, so the walk stops at that layer and treats it as a neutral
+ * mid-gray occluder — better than ignoring it (which would let a bright page
+ * base bleed through a dark photo). This is a heuristic: it captures solid
+ * colors and translucency precisely and image presence coarsely, with zero
+ * canvas and zero taint risk.
+ *
+ * @param point - Viewport coordinates to sample under.
+ * @param ignore - An element to skip (the glass surface itself).
+ * @returns A sampled {@link BackdropSample}, or {@link UNSAMPLED} when there is
+ * no DOM / no element under the point.
+ */
+export declare function domBackgroundStrategy(point: {
+    x: number;
+    y: number;
+}, ignore?: Element | null): BackdropSample;
+
+/** Result of {@link calculateElasticTranslation}. */
+export declare interface ElasticTranslation {
+    /** Horizontal nudge in CSS pixels. */
+    x: number;
+    /** Vertical nudge in CSS pixels. */
+    y: number;
+}
+
+/**
+ * Conservative, all-`false` capability snapshot. Exported so the hook and any
+ * consumer can render a stable degraded state during SSR / first paint without
+ * re-deriving the shape.
+ */
+export declare function getConservativeGlassCapabilities(): GlassCapabilities;
+
+/**
+ * Generate (or return a cached) displacement map for the given mode and size.
+ *
+ * Width/height are quantized to a 16px grid before both keying and rendering, so
+ * a resize storm of near-identical sizes collapses to a single render while
+ * keeping aspect-correct corners. Results are memoized in a bounded LRU
+ * (cap {@link CACHE_CAP}).
+ *
+ * Degenerate input (`width <= 0` or `height <= 0`, or non-finite) returns a 1×1
+ * transparent PNG instead of throwing, making the function SSR- and
+ * no-dimension-safe.
+ *
+ * @param mode - Which generator to use. Excludes `'turbulence'` (procedural, 004).
+ * @param width - Target map width in px.
+ * @param height - Target map height in px.
+ * @returns A `data:image/png;base64,…` URL.
+ */
+export declare function getDisplacementMap(mode: MapMode, width: number, height: number): string;
+
+/**
+ * Return the layered inset `box-shadow` string for the requested colour scheme.
+ *
+ * @param scheme - `'light'` or `'dark'`.
+ * @returns The comma-joined `box-shadow` value (see {@link GLASS_EDGE_LIGHT} /
+ * {@link GLASS_EDGE_DARK}).
+ */
+export declare function getGlassEdgeShadow(scheme: GlassEdgeScheme): string;
+
+/**
+ * Dark-mode bevel: the highlight direction is flipped to a cooler, dimmer
+ * top-left sheen and the lower-right inset shade is deepened so the rim still
+ * reads against dark backdrops without blowing out.
+ */
+export declare const GLASS_EDGE_DARK: string;
+
+/**
+ * Light-mode bevel: bright top-left inset highlight, softer bottom-right inset
+ * shade, plus a thin hairline ring for crispness. Tuned for glass over light or
+ * mid-tone backgrounds.
+ */
+export declare const GLASS_EDGE_LIGHT: string;
+
+/**
+ * Controlled/uncontrolled convention (locked here for the whole library — plan
+ * 007 / 012): any future stateful surface MUST accept a `value`/`defaultValue`
+ * pair plus an `onValueChange` callback and fall back to internal state when
+ * uncontrolled. `GlassButton` itself is stateless, so it exposes none.
+ */
+export declare const GlassButton: ForwardRefExoticComponent<GlassButtonProps & RefAttributes<HTMLButtonElement>>;
+
+export declare interface GlassButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Visual emphasis. @defaultValue `'primary'` */
+    variant?: GlassButtonVariant;
+    /** Sizing; `icon` is square and centers a single icon child. @defaultValue `'md'` */
+    size?: GlassButtonSize;
+    /**
+     * Render the single child element instead of a `<button>`, merging this
+     * component's props/className/ref onto it. The child then owns its own
+     * semantics and a11y (e.g. an `<a href>` for a link-styled button).
+     * @defaultValue `false`
+     */
+    asChild?: boolean;
+    /** Brief highlight sweep on press. @defaultValue `true` */
+    shine?: boolean;
+    /** Class applied to the isolated content layer (the span holding children). */
+    contentClassName?: string;
+    /** Escape hatch: pass-through overrides to the underlying `<LiquidGlass>`. */
+    glassProps?: Partial<Omit<LiquidGlassProps, 'children'>>;
+}
+
+export declare type GlassButtonSize = 'sm' | 'md' | 'lg' | 'icon';
+
+export declare type GlassButtonVariant = 'primary' | 'secondary' | 'subtle';
+
+/**
+ * Result of runtime capability detection. Every field is a plain boolean so the
+ * object is trivially serializable and cheap to compare across renders.
+ *
+ * Produced by `detectGlassCapabilities()` and surfaced to components via the
+ * `useGlassCapabilities()` hook. During SSR (and before mount) all fields are
+ * conservatively `false`.
+ */
+export declare type GlassCapabilities = {
+    /**
+     * Whether the browser supports `backdrop-filter` (or the `-webkit-` prefixed
+     * variant). Required for any frosted-glass blur at all.
+     */
+    supportsBackdropFilter: boolean;
+    /**
+     * Positive Blink-family detection (Chrome, Edge, Brave, Opera). Explicitly
+     * NOT Firefox and NOT Safari/WebKit.
+     */
+    isChromium: boolean;
+    /**
+     * Whether an SVG `feDisplacementMap` filter composites correctly over
+     * `backdrop-filter`. This is a Chromium-only rendering-pipeline quirk with no
+     * standardized `CSS.supports` probe, so it is derived from {@link isChromium}.
+     */
+    supportsSvgBackdropDisplacement: boolean;
+    /** Whether the user agent is Firefox (Gecko). */
+    isFirefox: boolean;
+    /**
+     * Whether the user has requested reduced motion via
+     * `(prefers-reduced-motion: reduce)`.
+     */
+    prefersReducedMotion: boolean;
+    /**
+     * Whether the user has requested reduced transparency via
+     * `(prefers-reduced-transparency: reduce)`. When `true`, `<LiquidGlass>`
+     * suppresses live SVG refraction and renders a frostier, more-opaque surface.
+     * Orthogonal to {@link canRefract} — it applies on every tier and changes no
+     * box geometry. The authoritative live source is `useReducedTransparency()`;
+     * this field is a point-in-time snapshot.
+     */
+    prefersReducedTransparency: boolean;
+    /**
+     * Whether the user has requested increased contrast via
+     * `(prefers-contrast: more)`. When `true`, `<LiquidGlass>` adds a solid,
+     * visible inset border, raises content legibility (a more-opaque surface
+     * fill), and tones down decorative saturation/aberration that harms contrast.
+     * Orthogonal to {@link canRefract} AND to {@link prefersReducedTransparency} —
+     * it applies on every tier, composes with reduced-transparency, and changes no
+     * box geometry. The authoritative live source is `usePrefersContrast()`; this
+     * field is a point-in-time snapshot.
+     */
+    prefersContrastMore: boolean;
+    /**
+     * The single gate later plans consult: `true` only when the full refraction
+     * effect can actually render
+     * (`supportsBackdropFilter && supportsSvgBackdropDisplacement`). When `false`,
+     * components must fall back to a degraded (non-refractive) presentation.
+     */
+    canRefract: boolean;
+};
+
+export declare const GlassCard: ForwardRefExoticComponent<GlassCardProps & RefAttributes<HTMLDivElement>>;
+
+export declare type GlassCardElevation = 'flat' | 'raised' | 'floating';
+
+export declare interface GlassCardProps extends HTMLAttributes<HTMLDivElement> {
+    /** Ambient lift under the card. @defaultValue `'raised'` */
+    elevation?: GlassCardElevation;
+    /**
+     * Render the single child element instead of a `<div>`, merging this
+     * component's props/className/ref onto it. The child then owns its semantics.
+     * @defaultValue `false`
+     */
+    asChild?: boolean;
+    /** Class applied to the isolated content layer (the wrapper holding children). */
+    contentClassName?: string;
+    /** Escape hatch: pass-through overrides to the underlying `<LiquidGlass>`. */
+    glassProps?: Partial<Omit<LiquidGlassProps, 'children'>>;
+}
+
+/**
+ * Lens focal point for the cross-browser copy-refraction path (plan 030),
+ * expressed as fractions of the lens box in `[0, 1]` (`{ x: 0.5, y: 0.5 }` is
+ * the center). It drives the refracted copy's `transform-origin`, so the warp
+ * reads as if the light bends around that point.
+ */
+export declare interface GlassCenter {
+    /** Horizontal focal point as a fraction of the lens width (`0`–`1`). */
+    x: number;
+    /** Vertical focal point as a fraction of the lens height (`0`–`1`). */
+    y: number;
+}
+
+/** Colour scheme selector for {@link getGlassEdgeShadow}. */
+export declare type GlassEdgeScheme = 'light' | 'dark';
+
+export declare const GlassSegmentedControl: ForwardRefExoticComponent<GlassSegmentedControlProps & RefAttributes<HTMLFieldSetElement>>;
+
+export declare interface GlassSegmentedControlProps {
+    /** The selectable segments. */
+    options: GlassSegmentedOption[];
+    /** Controlled selected value. When set, the component is controlled. */
+    value?: string;
+    /** Initial selected value when uncontrolled. Defaults to the first option. */
+    defaultValue?: string;
+    /** Fires on every user selection with the newly-selected value. */
+    onValueChange?: (value: string) => void;
+    /** Size variant. @defaultValue `'md'` */
+    size?: GlassSegmentedControlSize;
+    /**
+     * Accessible group label. Rendered into the `<legend>` (visually hidden unless
+     * `showLabel`) so screen-reader users hear the group's purpose.
+     */
+    label?: ReactNode;
+    /** Accessible group label as a plain string (alternative to `label`). */
+    'aria-label'?: string;
+    /** Show the `label` visually above the control instead of hiding it. */
+    showLabel?: boolean;
+    /** Class applied to the root `<fieldset>`. */
+    className?: string;
+    /** Inline styles merged onto the root `<fieldset>`. */
+    style?: CSSProperties;
+    /** Stable `name` for the radio group. Defaults to a generated id. */
+    name?: string;
+    /** Escape hatch: pass-through overrides to the indicator's `<LiquidGlass>`. */
+    glassProps?: Partial<Omit<LiquidGlassProps, 'children'>>;
+}
+
+export declare type GlassSegmentedControlSize = 'sm' | 'md' | 'lg';
+
+/** A single selectable segment. `label` and/or `icon` may be supplied. */
+export declare interface GlassSegmentedOption {
+    /** Stable value emitted via `onValueChange` and used to mark selection. */
+    value: string;
+    /** Visible text/content (optional when an `icon` carries the meaning). */
+    label?: ReactNode;
+    /** Leading icon (optional). Icon-only options are supported. */
+    icon?: ReactNode;
+    /** Disable this single option. */
+    disabled?: boolean;
+}
+
+/**
+ * Explicit lens size (CSS pixels) for the cross-browser copy-refraction path
+ * (plan 030). When omitted the lens is sized to the glass's measured dimensions.
+ */
+export declare interface GlassSize {
+    /** Lens width in CSS pixels. */
+    width: number;
+    /** Lens height in CSS pixels. */
+    height: number;
+}
+
+/**
+ * The two Liquid Glass material variants Apple distinguishes — selected with one
+ * intentional prop instead of hand-tuning opacity.
+ *
+ * - `regular` — the dependable, fully adaptive control surface. Exactly the
+ *   current behavior, including content-adaptive auto-tint when
+ *   {@link LiquidGlassProps.adaptiveTint} is enabled.
+ * - `clear` — a permanently MORE transparent material for media-rich contexts
+ *   (e.g. floating over a photo). It is **non-adaptive by definition**:
+ *   {@link LiquidGlassProps.adaptiveTint} is force-disabled, and an optional
+ *   dimming scrim sits behind the content so labels stay legible over busy media.
+ *
+ * Apple's guidance is that the two **should never be mixed** in the same context.
+ *
+ * @defaultValue `'regular'`
+ */
+export declare type GlassVariant = 'regular' | 'clear';
+
+/**
+ * Luminance at or above this value is classified `'light'`; below it, `'dark'`.
+ *
+ * `0.5` is the midpoint of the normalized `[0, 1]` luminance range. It is a
+ * coarse, deliberately simple split: relative luminance is already perceptually
+ * weighted (see {@link relativeLuminance}), so a midpoint cut maps cleanly to
+ * "should dark text or light text sit on this?" for the adaptive-tint consumer
+ * (plan 018). Exposed as a constant so consumers and tests share one threshold.
+ */
+export declare const LIGHT_DARK_THRESHOLD = 0.5;
+
+/**
+ * The liquid-glass refraction primitive. See the file header for the layer
+ * stack, application mechanism, and measurement strategy.
+ *
+ * ## Motion + rim lighting (plan 005)
+ *
+ * The elastic stretch/translate (from {@link useMousePosition} + the pure
+ * `motion.ts` math) and the rim/highlight layers are PURE CSS — they render in
+ * every browser regardless of `canRefract`. The `transform` is applied to the
+ * GLASS SURFACE and the rim/highlight layers (which are siblings of the content
+ * layer), so the elastic distortion never warps the crisp `children`. The pure-
+ * CSS bevel (`glass-edge.ts`) is an inset `box-shadow` on the surface, while the
+ * outer drop-shadow/glow is a SEPARATE sibling element rendered BEHIND the
+ * `overflow:hidden` surface so clipping can't eat it.
+ *
+ * ## Specular hotspot + glow-on-press (plan 016)
+ *
+ * The highlight layer is a POSITIONED `radial-gradient` specular hotspot whose
+ * center tracks the pointer over the glass (driven by `--lg-spec-x/y` from
+ * {@link useMousePosition}), with a neutral top-biased fallback at rest. A second
+ * `[data-lg-press-glow]` layer blooms a radial glow from the contact point on
+ * press and fades out. Both are pure CSS (gradient/opacity/transform), render in
+ * EVERY engine regardless of `canRefract` (polish, not refraction), and are
+ * GATED on {@link useReducedMotion}: when reduced-motion is set the hotspot is
+ * static (neutral, no tracking) and the press glow snaps without animating. They
+ * are decorative siblings (aria-hidden, pointer-events:none) and never touch
+ * layout/geometry. They compose with {@link GlassButton}'s diagonal `shine`
+ * sweep (a `::after` on the button element) — different nodes, different layers.
+ */
+export declare function LiquidGlass({ children, displacement, displacementScale, blurAmount, saturation, aberrationIntensity, elasticity, cornerRadius, padding, overLight, adaptiveTint, scrollAwareShadow, variant, mode, refract, size, center, behind, className, style, onClick, globalMousePos, mouseOffset, mouseContainer, }: LiquidGlassProps): ReactNode;
+
+/**
+ * PLATFORM-NEUTRAL props for the `<LiquidGlass>` PRIMITIVE.
+ *
+ * The shared base that BOTH the web (`liquid-glass.tsx`) and React Native
+ * (`liquid-glass.native.tsx`, plan 025) surfaces extend. It holds every prop
+ * that does NOT depend on DOM types, so the native surface can build on it
+ * without leaking `CSSProperties` / DOM event handlers. The web
+ * {@link LiquidGlassProps} extends this with the DOM-only `style` / `onClick` /
+ * pointer props; the native barrel defines its own `style?: ViewStyle` /
+ * `onPress?` over this same core.
+ *
+ * Every prop except {@link children} is optional — the primitive ships sensible
+ * defaults. Defaults documented here are the contract; the implementation plan
+ * (004+) must honor them.
+ */
+declare interface LiquidGlassCoreProps {
+    /** Content rendered inside the glass surface. */
+    children: ReactNode;
+    /**
+     * Opt into the live SVG refraction/displacement pass (WEB-ONLY progressive
+     * enhancement). When `false` (the default) the glass renders the frosted
+     * fallback look — `blur()`/`saturate()` backdrop plus the pure-CSS bevel —
+     * with no `feDisplacementMap`.
+     *
+     * - **Web:** when `true` AND the browser can refract (Chromium), the SVG
+     *   displacement filter is attached; otherwise it degrades to the frosted look.
+     * - **React Native:** a documented NO-OP. RN has no SVG-over-backdrop
+     *   compositing, so the prop is accepted for a single cross-platform contract
+     *   but the surface always renders the frosted fallback.
+     *
+     * @defaultValue `false`
+     */
+    displacement?: boolean;
+    /**
+     * Strength of the displacement/refraction distortion. Higher values bend the
+     * backdrop more aggressively.
+     *
+     * @defaultValue `70`
+     */
+    displacementScale?: number;
+    /**
+     * Backdrop blur radius in pixels applied behind the glass.
+     *
+     * @defaultValue `0.0625`
+     */
+    blurAmount?: number;
+    /**
+     * Backdrop saturation multiplier (`1` = unchanged). Boosts color vibrancy of
+     * the content seen through the glass.
+     *
+     * @defaultValue `140`
+     */
+    saturation?: number;
+    /**
+     * Intensity of the chromatic aberration (RGB channel separation) at the
+     * refracted edges. `0` disables it.
+     *
+     * @defaultValue `2`
+     */
+    aberrationIntensity?: number;
+    /**
+     * How elastically the glass reacts to pointer movement. `0` is rigid; higher
+     * values produce a softer, more rubbery follow.
+     *
+     * @defaultValue `0.15`
+     */
+    elasticity?: number;
+    /**
+     * Corner radius of the glass surface. A number is treated as pixels; a string
+     * is passed through as a CSS length (e.g. `'1rem'`, `'50%'`).
+     *
+     * @defaultValue `999`
+     */
+    cornerRadius?: number | string;
+    /**
+     * Inner padding of the glass surface. A number is treated as pixels; a string
+     * is passed through as a CSS shorthand (e.g. `'8px 16px'`).
+     *
+     * @defaultValue `'24px'`
+     */
+    padding?: number | string;
+    /**
+     * Hint that the glass sits over a light background, so it tunes its tint and
+     * contrast for legibility.
+     *
+     * This is the MANUAL override. When set explicitly it ALWAYS wins over
+     * {@link adaptiveTint} (see that prop's precedence note) — the two never fight.
+     *
+     * @defaultValue `false`
+     */
+    overLight?: boolean;
+    /**
+     * Opt into CONTENT-ADAPTIVE auto-tint (plan 018). When `true`, the glass
+     * samples the luminance of the backdrop behind it (via the plan-017 sampler)
+     * and automatically shifts toward a light or dark treatment — the SAME tint /
+     * displacement / blur plumbing {@link overLight} already drives — so foreground
+     * content stays legible without hand-tuning `overLight`. A bright backdrop
+     * yields the light treatment (`overLight`-equivalent), a dark backdrop the
+     * default treatment.
+     *
+     * ## Precedence (documented rule)
+     *
+     * An EXPLICIT {@link overLight} always wins. `adaptiveTint` only drives the
+     * light/dark treatment when `overLight` is left unset/undefined:
+     *
+     * ```ts
+     * effectiveOverLight = overLight ?? (adaptiveTint && scheme ? scheme === 'light' : false)
+     * ```
+     *
+     * ## SSR / hydration
+     *
+     * The server and the first client paint render the default (unsampled,
+     * conservative) treatment, so hydration never mismatches. The sampled treatment
+     * is applied in an effect after mount.
+     *
+     * ## Graceful degradation
+     *
+     * When the backdrop cannot be sampled (cross-origin-tainted canvas, no canvas,
+     * SSR) the reading is `sampled: false` and auto-tint falls back to
+     * `overLight ?? false` with no error, no flicker loop, and no `console.error`.
+     *
+     * ## Accessibility interaction
+     *
+     * Under `(prefers-contrast: more)` (plan 014) the high-contrast treatment wins:
+     * auto-tint never undercuts the increased-contrast surface/legibility treatment.
+     *
+     * ## Limitation
+     *
+     * Auto-tint is BEST-EFFORT legibility. Critical text over unknown or
+     * cross-origin backdrops (which cannot be sampled) should be verified manually —
+     * the auto path silently falls back rather than guessing.
+     *
+     * @defaultValue `false`
+     */
+    adaptiveTint?: boolean;
+    /**
+     * Opt into SCROLL-AWARE SHADOW (plan 021). When `true`, the glass's decoupled
+     * outer drop-shadow (the `[data-lg-shadow]` sibling rendered behind the clipped
+     * surface) modulates its depth/darkness from the backdrop behind the element
+     * (via the plan-017 sampler): it DEEPENS and DARKENS over a dark/dense backdrop
+     * (reinforcing the "floating above content" read as text scrolls beneath) and
+     * EASES/LIGHTENS over a light/solid one. Apple's Liquid Glass does exactly this
+     * as content scrolls under a pinned glass bar.
+     *
+     * ## What it touches
+     *
+     * ONLY the existing drop-shadow sibling's blur/offset/opacity vary. The shadow
+     * stays a SIBLING of the `overflow:hidden` glass surface (never a box-shadow on
+     * the clipped node — the plan-005 layering invariant); no new layer is added.
+     *
+     * ## SSR / hydration
+     *
+     * The server and the first client paint render the conservative static shadow,
+     * so hydration never mismatches. The modulated shadow is applied in an effect
+     * after mount; sampling is throttled by the hook.
+     *
+     * ## Graceful degradation
+     *
+     * When the backdrop cannot be sampled (cross-origin-tainted canvas, no canvas,
+     * SSR) the reading is `sampled: false` and the shadow falls back to the current
+     * static shadow with no error and no flicker loop.
+     *
+     * ## Reduced motion
+     *
+     * Under `(prefers-reduced-motion: reduce)` the shadow does not animate between
+     * depths — it snaps/stays static (no transition).
+     *
+     * This is ADDITIVE and non-breaking: omitting it (default `false`) keeps today's
+     * rendering byte-for-byte and leaves the committed pixel baseline unchanged.
+     *
+     * @defaultValue `false`
+     */
+    scrollAwareShadow?: boolean;
+    /**
+     * The Liquid Glass material variant. See {@link GlassVariant}.
+     *
+     * - `'regular'` (default) — EXACTLY the current behavior, including
+     *   content-adaptive auto-tint when {@link adaptiveTint} is enabled. The
+     *   dependable, fully adaptive control surface.
+     * - `'clear'` — a permanently MORE transparent surface (lower fill opacity /
+     *   reduced tint) for media-rich contexts, with an optional dimming scrim
+     *   behind the content so labels stay legible over busy media. Geometry is
+     *   unchanged from `'regular'`.
+     *
+     * ## Interaction rules
+     *
+     * - **Clear is non-adaptive by definition.** In `'clear'`, {@link adaptiveTint}
+     *   is a **no-op** — the glass never samples the backdrop and never flips its
+     *   tint/ink. (Use `'regular'` + `adaptiveTint` for the adaptive material.)
+     * - **`overLight` still nudges legibility, not adaptivity.** In `'clear'`, an
+     *   explicit {@link overLight} may still tune the dimming/legibility treatment,
+     *   but it does NOT re-enable the adaptive sampling path.
+     * - **Accessibility wins.** Under `(prefers-contrast: more)` (plan 014) the
+     *   high-contrast treatment STILL applies in both variants — a11y beats the
+     *   Clear aesthetic, so Clear surfaces become legible/high-contrast when the
+     *   user asks for it.
+     *
+     * Per Apple's guidance, the two variants **should never be mixed** in the same
+     * context. This is ADDITIVE and non-breaking: omitting it keeps today's
+     * behavior exactly.
+     *
+     * @defaultValue `'regular'`
+     */
+    variant?: GlassVariant;
+    /**
+     * Which displacement algorithm to use. See {@link DisplacementMode}.
+     *
+     * @defaultValue `'standard'`
+     */
+    mode?: DisplacementMode;
+    /**
+     * CROSS-BROWSER copy-refraction content (plan 030). Distinct from
+     * {@link displacement} (the Chromium-only `backdrop-filter: url(#…)` bend of
+     * the LIVE page behind the glass): this path applies the SAME SVG displacement
+     * filter as an ELEMENT `filter: url(#…)` to a COPY of content, which DOES run in
+     * Chromium, Firefox, AND WebKit. The refracted copy is a decorative sibling
+     * BEHIND the crisp {@link children} (never an ancestor of them), so interactive
+     * content stays selectable and clickable.
+     *
+     * - **`refract` set** — the copy layer renders THIS node (a lens floated over
+     *   content the glass doesn't own), filtered; {@link behind} fills the bleed and
+     *   crisp {@link children} render on top. The node re-renders with the parent
+     *   (React keeps it in sync) and the lens region re-measures on resize.
+     * - **`refract` unset but {@link size}/{@link center} set** — IN-PLACE mode: the
+     *   glass refracts a copy of its OWN {@link children} through the element filter,
+     *   with the crisp children on top.
+     *
+     * Omitting `refract`, {@link size}, AND {@link center} disables this path
+     * entirely — the render is byte-for-byte the {@link displacement} behavior.
+     *
+     * ## Contract: the refracted copy must be PRESENTATIONAL
+     *
+     * The copy layer renders a SECOND instance of the copied node (`refract`, or —
+     * in IN-PLACE mode — a copy of {@link children}). It is `aria-hidden` + `inert`
+     * + `pointer-events: none`, so it is hidden from the a11y tree and cannot be
+     * interacted with. But React still MOUNTS it, so the copied subtree should be
+     * PURELY PRESENTATIONAL:
+     *
+     * - **No `id`s / label targets / in-page anchor targets** — they would be
+     *   duplicated in the DOM (`getElementById` / `label[for]` / `#hash` could bind
+     *   the hidden copy).
+     * - **No effects / focus-on-mount / data fetching / callback refs** — they run
+     *   for BOTH instances.
+     * - **No focusable controls** on engines that don't honor `inert` (older
+     *   Safari/Firefox), where they could otherwise become tabbable inside an
+     *   `aria-hidden` subtree.
+     *
+     * For anything non-trivial, prefer `refract={<decorative node>}` (a background
+     * you fully control) over IN-PLACE copying of rich interactive `children`.
+     * Passing `refract={null}` opts in but renders an EMPTY lens (only the
+     * {@link behind} bleed) — it does NOT fall back to copying `children`.
+     *
+     * **React Native:** a documented NO-OP (no SVG filters; always frosted).
+     *
+     * @defaultValue `undefined`
+     */
+    refract?: ReactNode;
+    /**
+     * Explicit lens {@link GlassSize} for the copy-refraction path (plan 030). When
+     * omitted the lens is sized to the glass's measured dimensions. Presence of this
+     * prop (with or without {@link refract}) opts INTO the cross-browser copy
+     * refraction in IN-PLACE mode (refract a copy of the own {@link children}).
+     *
+     * **React Native:** a documented NO-OP.
+     *
+     * @defaultValue `undefined` (use measured dimensions)
+     */
+    size?: GlassSize;
+    /**
+     * Lens focal point ({@link GlassCenter}, fractions in `[0, 1]`) for the
+     * copy-refraction path (plan 030). Drives the refracted copy's
+     * `transform-origin`. Presence opts into the cross-browser copy refraction in
+     * IN-PLACE mode, same as {@link size}.
+     *
+     * **React Native:** a documented NO-OP.
+     *
+     * @defaultValue `{ x: 0.5, y: 0.5 }` (center)
+     */
+    center?: GlassCenter;
+    /**
+     * Bleed fill (any CSS `background` value) painted behind the refracted copy on
+     * the copy-refraction path (plan 030), so the displacement has something to pull
+     * from where the copied content doesn't cover the lens box. Most useful with
+     * {@link refract} (a lens over foreign content); usually unnecessary for
+     * IN-PLACE mode. No effect unless the copy-refraction path is active.
+     *
+     * **React Native:** a documented NO-OP.
+     *
+     * @defaultValue `undefined`
+     */
+    behind?: string;
+    /** Additional class name(s) applied to the outermost glass element. */
+    className?: string;
+}
+
+/**
+ * Props for the WEB `<LiquidGlass>` PRIMITIVE.
+ *
+ * The platform-neutral {@link LiquidGlassCoreProps} plus the DOM-only props the
+ * web surface needs: inline `style`, the `onClick` handler, and the externally
+ * controlled pointer inputs. This is the same surface the library has always
+ * exposed — splitting the core out is type-only and changes nothing for web
+ * consumers.
+ */
+export declare type LiquidGlassProps = LiquidGlassCoreProps & {
+    /** Inline styles merged onto the outermost glass element. */
+    style?: CSSProperties;
+    /** Click handler forwarded to the glass surface. */
+    onClick?: MouseEventHandler<HTMLDivElement>;
+    /**
+     * Externally controlled global pointer position. When provided, the primitive
+     * uses this instead of subscribing to its own pointer events — useful for
+     * coordinating many glass surfaces from one shared tracker.
+     *
+     * Leave undefined for the uncontrolled default (the primitive tracks the
+     * pointer itself).
+     */
+    globalMousePos?: MousePos;
+    /**
+     * Externally controlled pointer offset relative to the glass element's
+     * center, in CSS pixels. Paired with {@link globalMousePos} for fully
+     * controlled motion.
+     */
+    mouseOffset?: MousePos;
+    /**
+     * Element (or ref to one) whose bounds define the coordinate space for
+     * pointer tracking. Defaults to the viewport when omitted or `null`.
+     *
+     * @defaultValue `null` (viewport)
+     */
+    mouseContainer?: RefObject<HTMLElement | null> | HTMLElement | null;
+};
+
+/**
+ * Classify a normalized luminance as `'light'` or `'dark'`.
+ *
+ * @param luminance - Relative luminance in `[0, 1]`.
+ * @returns `'light'` when `luminance >= ` {@link LIGHT_DARK_THRESHOLD}, else
+ * `'dark'`.
+ */
+export declare function luminanceToScheme(luminance: number): BackdropScheme;
+
+/** Modes that resolve to a `data:` URL map. `'turbulence'` is procedural (plan 004). */
+declare type MapMode = Exclude<DisplacementMode, 'turbulence'>;
+
+/** A container reference accepted by {@link useMousePosition}. */
+export declare type MouseContainer = RefObject<HTMLElement | null> | HTMLElement | null | undefined;
+
+/**
+ * A 2D pointer position in CSS pixels, used for mouse-driven motion/elasticity.
+ *
+ * Coordinates are interpreted relative to whatever container the consumer wires
+ * up via {@link LiquidGlassProps.mouseContainer} (viewport by default).
+ */
+export declare type MousePos = {
+    /** Horizontal position in CSS pixels. */
+    x: number;
+    /** Vertical position in CSS pixels. */
+    y: number;
+};
+
+/** Return shape of {@link useMousePosition}. */
+export declare interface MousePositionState {
+    /** Absolute pointer position in CSS pixels (`{0,0}` when inactive). */
+    mousePos: MousePos;
+    /** Pointer offset from the tracked element center, in CSS pixels. */
+    offset: MousePos;
+    /**
+     * Whether motion is live: `false` under SSR, reduced-motion, or touch — in
+     * which case `mousePos`/`offset` are neutral and the component must not
+     * animate.
+     */
+    isActive: boolean;
+}
+
+/**
+ * Parse a CSS color string into RGB + alpha.
+ *
+ * Handles the forms `getComputedStyle` actually returns for
+ * `background-color`: `rgb(r, g, b)`, `rgba(r, g, b, a)`, and the special
+ * `transparent` / empty values (alpha 0). Modern engines may also emit
+ * `rgb(r g b / a)` (space-separated, slash alpha); both are accepted. Anything
+ * unrecognized (e.g. exotic `color()` functions) is treated as fully
+ * transparent so it is skipped rather than mis-composited.
+ *
+ * @param value - A computed CSS color string.
+ * @returns `{ r, g, b, a }` with channels in `[0, 255]` and `a` in `[0, 1]`.
+ */
+export declare function parseCssColor(value: string | null | undefined): Rgb & {
+    a: number;
+};
+
+/**
+ * Relative luminance of an sRGB color, per the WCAG 2.x definition.
+ *
+ * Linearizes each channel (see {@link srgbChannelToLinear}) then applies the
+ * Rec. 709 luma weights (`0.2126 R + 0.7152 G + 0.0722 B`). The result is in
+ * `[0, 1]`: `0` for black, `1` for white, with green contributing most and blue
+ * least — matching human brightness perception.
+ *
+ * @param r - Red channel, `[0, 255]`.
+ * @param g - Green channel, `[0, 255]`.
+ * @param b - Blue channel, `[0, 255]`.
+ * @returns Relative luminance in `[0, 1]`.
+ *
+ * @example
+ * relativeLuminance(0, 0, 0); // 0   (black)
+ * relativeLuminance(255, 255, 255); // 1   (white)
+ */
+export declare function relativeLuminance(r: number, g: number, b: number): number;
+
+/**
+ * Backdrop-luminance sampling (plan 017) — the React-free core.
+ *
+ * Apple's Liquid Glass is content-adaptive: the material reads the brightness of
+ * what sits behind it and adjusts its tint for legibility. There is no reliable,
+ * cheap, universal way to read "the pixels behind an arbitrary element" in a
+ * browser — `backdrop-filter` happens in the compositor, never exposed to JS. So
+ * this module ships a PLUGGABLE, degrading sampling strategy plus the pure
+ * luminance math, all framework-free. The React hook
+ * (`useBackdropLuminance`) wraps this with effects, throttling, and SSR guards.
+ *
+ * Two strategies, ONE contract ({@link BackdropSample}):
+ *
+ * 1. **DOM-background (default).** Walk the stacking order behind the element's
+ *    center via `document.elementsFromPoint`, read each layer's computed
+ *    `background-color` (and detect opaque `background-image`s), and composite
+ *    them front-to-back into one estimated backdrop color. Cheap, synchronous,
+ *    no canvas, and NEVER taints — it only reads CSSOM, not pixels. It cannot see
+ *    *image content* luminance (only that an opaque image exists), which is an
+ *    accepted trade-off for the zero-cost default.
+ * 2. **Canvas snapshot (opt-in).** A caller-supplied function that paints the
+ *    backdrop into a canvas and returns its average color. This CAN read real
+ *    image luminance but can TAINT: a cross-origin image drawn without CORS makes
+ *    `getImageData` throw `SecurityError`. This module treats any throw from the
+ *    sampler as "could not sample" and returns an unsampled result — it never
+ *    rethrows and never logs. (The hook layer enforces the same contract.)
+ *
+ * This module is intentionally independent of `liquid-glass.tsx`: it is imported
+ * only by consumers opting into adaptive tint, so it tree-shakes out of the
+ * default `<LiquidGlass>` path and adds zero bytes there.
+ */
+/** A linear-RGB / sRGB color triple, each channel in `[0, 255]`. */
+export declare interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+
+/**
+ * Signed distance from point `(x, y)` to a rounded rectangle of size `w × h`
+ * **centered at the origin**, with corner radius `r`.
+ *
+ * Convention: **negative inside**, **zero on the border**, **positive outside**
+ * (the standard SDF sign convention). The radius is clamped to half the smaller
+ * side so it can never exceed the rectangle.
+ *
+ * @param x - X coordinate relative to the rectangle center.
+ * @param y - Y coordinate relative to the rectangle center.
+ * @param w - Full width of the rectangle.
+ * @param h - Full height of the rectangle.
+ * @param r - Corner radius.
+ * @returns Signed distance in the same units as the inputs.
+ */
+export declare function roundedRectSDF(x: number, y: number, w: number, h: number, r: number): number;
+
+/**
+ * Run a sampling strategy with a total taint/error guard.
+ *
+ * If the strategy throws for ANY reason — most importantly a `SecurityError`
+ * from `getImageData` on a cross-origin-tainted canvas — this returns
+ * {@link UNSAMPLED} instead of propagating. It deliberately does NOT log: a
+ * tainted backdrop is an expected, recoverable condition, not an application
+ * error, and console noise on every animation frame would be hostile.
+ *
+ * @param strategy - The strategy to invoke.
+ * @param point - The viewport point to sample.
+ * @returns The strategy's result, or {@link UNSAMPLED} on any throw.
+ */
+export declare function safeSample(strategy: SamplingStrategy, point: {
+    x: number;
+    y: number;
+}): BackdropSample;
+
+/**
+ * Sample the estimated backdrop luminance under a viewport point.
+ *
+ * Thin orchestrator: resolves the strategy (default {@link domBackgroundStrategy})
+ * and runs it through {@link safeSample} so a tainted canvas or any failure
+ * yields {@link UNSAMPLED} rather than throwing.
+ *
+ * @param point - Viewport coordinates (typically the glass element's center).
+ * @param options - {@link SampleBackdropOptions}.
+ * @returns A {@link BackdropSample}.
+ */
+export declare function sampleBackdropLuminance(point: {
+    x: number;
+    y: number;
+}, options?: SampleBackdropOptions): BackdropSample;
+
+/**
+ * Options for {@link sampleBackdropLuminance}.
+ */
+export declare interface SampleBackdropOptions {
+    /**
+     * Override the sampling strategy. Defaults to {@link domBackgroundStrategy}.
+     * Pass a canvas-based strategy here to opt into pixel-accurate sampling
+     * (taint-safe: any throw becomes {@link UNSAMPLED}).
+     */
+    strategy?: SamplingStrategy;
+    /**
+     * The element to exclude from the DOM walk (the glass surface itself) so its
+     * own background is not mistaken for the backdrop. Only used by the default
+     * DOM strategy.
+     */
+    ignore?: Element | null;
+}
+
+/**
+ * A sampling strategy: given a viewport point, return a backdrop sample (or
+ * {@link UNSAMPLED}). Pluggable so consumers can swap the default DOM walk for a
+ * canvas-snapshot path.
+ *
+ * Implementations MUST NOT throw — a strategy that cannot read (e.g. a tainted
+ * canvas) returns {@link UNSAMPLED}. See {@link safeSample}, which enforces this
+ * even for a misbehaving strategy.
+ */
+export declare type SamplingStrategy = (point: {
+    x: number;
+    y: number;
+}) => BackdropSample;
+
+/**
+ * Standard GLSL-style smoothstep. Returns `0` for `t <= a`, `1` for `t >= b`,
+ * and a smooth Hermite interpolation (`3u² − 2u³`) in between. Clamps outside
+ * the `[a, b]` range. If `a === b` it degenerates to a step at `a`.
+ *
+ * @param a - Lower edge.
+ * @param b - Upper edge.
+ * @param t - Value to interpolate.
+ * @returns A value in `[0, 1]`.
+ */
+export declare function smoothStep(a: number, b: number, t: number): number;
+
+/** The canonical "we could not sample" result. */
+export declare const UNSAMPLED: BackdropSample;
+
+/**
+ * Estimate the luminance of the backdrop behind `ref`'s element.
+ *
+ * @param ref - Ref to the glass element whose backdrop should be sampled. Its
+ * center point drives the sample, and the element itself is excluded from the
+ * DOM walk so its own background is not mistaken for the backdrop.
+ * @param options - {@link UseBackdropLuminanceOptions}.
+ * @returns A {@link BackdropSample}: {@link UNSAMPLED} during SSR / before mount /
+ * when disabled / on taint, otherwise the live reading.
+ */
+export declare function useBackdropLuminance(ref: RefObject<HTMLElement | null>, options?: UseBackdropLuminanceOptions): BackdropSample;
+
+/** Options for {@link useBackdropLuminance}. */
+export declare interface UseBackdropLuminanceOptions {
+    /**
+     * Custom sampling strategy (e.g. a canvas-snapshot strategy from
+     * `createCanvasSnapshotStrategy`). Defaults to the canvas-free DOM-background
+     * walk. Any throw from the strategy is caught and surfaced as an unsampled
+     * result.
+     */
+    strategy?: SamplingStrategy;
+    /**
+     * Re-sample when the window scrolls. Default `true`. Scroll changes what is
+     * behind the element, so the reading goes stale without this.
+     */
+    resampleOnScroll?: boolean;
+    /**
+     * Re-sample when the window resizes. Default `true`.
+     */
+    resampleOnResize?: boolean;
+    /**
+     * Skip sampling entirely (returns {@link UNSAMPLED}). Lets a consumer disable
+     * the work without unmounting the hook — e.g. when adaptive tint is off.
+     */
+    disabled?: boolean;
+}
+
+/**
+ * Detect liquid-glass capabilities on the client.
+ *
+ * @returns Conservative all-`false` {@link GlassCapabilities} until mounted,
+ * then the detected capabilities for the current browser.
+ */
+export declare function useGlassCapabilities(): GlassCapabilities;
+
+/**
+ * Track the pointer relative to an element center.
+ *
+ * @returns A {@link MousePositionState}: neutral (and `isActive: false`) under
+ * SSR, reduced-motion, touch, or controlled-with-no-data; live otherwise.
+ */
+export declare function useMousePosition(options?: UseMousePositionOptions): MousePositionState;
+
+/** Inputs accepted by {@link useMousePosition}. */
+export declare interface UseMousePositionOptions {
+    /**
+     * Element (or ref) whose bounds define the tracking frame. When provided, the
+     * pointer offset is measured against this container's center; otherwise the
+     * tracked element's own center is used.
+     */
+    container?: MouseContainer;
+    /**
+     * Externally controlled absolute pointer position. When set, the hook uses it
+     * verbatim instead of subscribing to pointer events.
+     */
+    globalMousePos?: MousePos;
+    /**
+     * Externally controlled offset from the element center. Paired with
+     * {@link UseMousePositionOptions.globalMousePos} for fully controlled motion;
+     * when present it is used directly as the offset.
+     */
+    mouseOffset?: MousePos;
+    /**
+     * The element whose center the offset is measured from when no `container` is
+     * supplied — typically the glass wrapper itself.
+     */
+    elementRef?: RefObject<HTMLElement | null>;
+}
+
+/**
+ * `usePrefersContrast()` — the SINGLE live source of increased-contrast state.
+ *
+ * This hook is authoritative for the whole library (plan 014), mirroring
+ * `useReducedTransparency` (013) and `useReducedMotion` (005) exactly:
+ *
+ * - It subscribes to `matchMedia('(prefers-contrast: more)')` AND its `'change'`
+ *   event, so it reacts when the user toggles the OS "Increase contrast" setting
+ *   mid-session — not just on mount.
+ * - It is SSR-safe: it returns `false` (no-increase default) before mount and
+ *   when `window` / `matchMedia` are unavailable, so server and first-client
+ *   render agree and never crash. Browsers that don't understand the query report
+ *   `matches: false`, so the conservative default holds there too.
+ *
+ * When this returns `true`, `<LiquidGlass>` adds a SOLID, visible inset border,
+ * raises content legibility (a more-opaque scheme-aware surface fill), and tones
+ * down decorative saturation/aberration that harms contrast. It is an axis
+ * ORTHOGONAL to the 3 capability tiers AND to reduced-transparency (013) — both
+ * a11y axes may be active at once and must stay legible and shift-free. No other
+ * code path may call `matchMedia('(prefers-contrast: more)')` reactively. (The
+ * point-in-time `prefersContrastMore` snapshot in `capabilities.ts` may stay for
+ * one-shot detection, but it is not the live reactive source.)
+ */
+/**
+ * Live increased-contrast state.
+ *
+ * @returns `false` during SSR / before mount, then the real
+ * `(prefers-contrast: more)` value, updating on OS-level changes.
+ */
+export declare function usePrefersContrast(): boolean;
+
+/**
+ * `useReducedMotion()` — the SINGLE live source of reduced-motion state.
+ *
+ * This hook is authoritative for the whole library (plan 005 eng-review):
+ *
+ * - It subscribes to `matchMedia('(prefers-reduced-motion: reduce)')` AND its
+ *   `'change'` event, so it reacts when the user toggles the OS "Reduce motion"
+ *   setting mid-session — not just on mount.
+ * - It is SSR-safe: it returns `false` (no-motion default) before mount and when
+ *   `window` / `matchMedia` are unavailable, so server and first-client render
+ *   agree and never crash.
+ *
+ * Every motion-aware consumer — {@link useMousePosition} (005), the
+ * unsupported-browser fallback path (006), and the segmented control (012) —
+ * reads reduced-motion state through THIS hook. No other code path may call
+ * `matchMedia('(prefers-reduced-motion: reduce)')` reactively. (The point-in-time
+ * `prefersReducedMotion` snapshot in `capabilities.ts` may stay for one-shot
+ * detection, but it is not the live reactive source.)
+ */
+/**
+ * Live reduced-motion state.
+ *
+ * @returns `false` during SSR / before mount, then the real
+ * `(prefers-reduced-motion: reduce)` value, updating on OS-level changes.
+ */
+export declare function useReducedMotion(): boolean;
+
+/**
+ * `useReducedTransparency()` — the SINGLE live source of reduced-transparency state.
+ *
+ * This hook is authoritative for the whole library (plan 013), mirroring
+ * `useReducedMotion` (005) exactly:
+ *
+ * - It subscribes to `matchMedia('(prefers-reduced-transparency: reduce)')` AND
+ *   its `'change'` event, so it reacts when the user toggles the OS "Reduce
+ *   transparency" setting mid-session — not just on mount.
+ * - It is SSR-safe: it returns `false` (no-reduction default) before mount and
+ *   when `window` / `matchMedia` are unavailable, so server and first-client
+ *   render agree and never crash. Browsers that don't understand the query
+ *   report `matches: false`, so the conservative default holds there too.
+ *
+ * When this returns `true`, `<LiquidGlass>` forces the existing no-filter path
+ * (omitting the SVG `url(#id)` refraction) and raises the surface fill opacity
+ * for a frostier, more-opaque result. No other code path may call
+ * `matchMedia('(prefers-reduced-transparency: reduce)')` reactively. (The
+ * point-in-time `prefersReducedTransparency` snapshot in `capabilities.ts` may
+ * stay for one-shot detection, but it is not the live reactive source.)
+ */
+/**
+ * Live reduced-transparency state.
+ *
+ * @returns `false` during SSR / before mount, then the real
+ * `(prefers-reduced-transparency: reduce)` value, updating on OS-level changes.
+ */
+export declare function useReducedTransparency(): boolean;
+
+/**
+ * Public entry point for @aberhamm/liquid-glass-react.
+ *
+ * Plan 002 establishes the load-bearing contracts: public types, runtime
+ * capability detection, and the React hook. Rendering, the SVG filter, and the
+ * `<LiquidGlass>` component itself land in later plans.
+ */
+export declare const VERSION = "0.0.0";
+
+export { }