vireglass 0.1.0

package/dist/material-CkUHUBoy.d.cts

@@ -0,0 +1,408 @@
+type VireGlassTint = {
+    r: number;
+    g: number;
+    b: number;
+};
+type VireGlassMaterial = {
+    /** Index of refraction of the medium. Water 1.33, glass 1.5, sapphire 1.77. */
+    ior: number;
+    /** Glass thickness, dp. Drives center magnification and absorption. */
+    thickness: number;
+    /** Bevel width, dp. Absolute: on real glass the rim doesn't depend on the piece's size. */
+    bevel: number;
+    /** Surface roughness: backdrop haziness and highlight blur. */
+    roughness: number;
+    /** Response to device orientation, 0 means the light is locked to the screen. */
+    environment: number;
+    /** Not physics but a legibility requirement: how strongly the glass has to separate its own
+     *  lightness from the ink drawn over it. 0 means the glass is simply transparent. */
+    legibility: number;
+    /** Dimming layer UNDER the glass, 0..1. For the transparent (Clear) variant this is what
+     *  provides legibility: that glass has no adaptation, and without dimming the ink drowns over
+     *  bright content.
+     *
+     *  Not to be confused with the mobile surface's `dim` prop: that one compensates for a platform
+     *  capture quirk (BlurView can't see a scrim drawn over the content), while this is a property
+     *  of the material itself. */
+    dimming: number;
+    /** Lightness of what the app draws OVER the glass: 1 is light icons and text, 0 is dark. A
+     *  cause, not a knob: the calling screen knows it. */
+    ink: number;
+    /** Minimum PRESENCE of the element itself: how far its body must stand off in lightness from
+     *  the backdrop behind it. Not the same as `legibility` — that's about the ink OVER the glass,
+     *  this is about the element itself. Over a uniform backdrop the glass has nothing to refract,
+     *  and the element disappears; for a control that's unacceptable. 0 means no presence is
+     *  required.
+     *
+     *  The sign is taken FROM THE BACKDROP, not from ink polarity: over dark the body lightens,
+     *  over light it darkens. So the requirement works the same way on any backdrop. */
+    presence: number;
+    /** Surface film thickness, nm. This is where interference comes from: the optical path
+     *  difference in the film becomes comparable to the wavelength, and the reflection picks up
+     *  iridescence. 0 means no film. */
+    film: number;
+};
+declare const MATERIAL_RANGES: {
+    readonly ior: readonly [1, 2];
+    readonly thickness: readonly [0, 60];
+    readonly bevel: readonly [0, 40];
+    readonly roughness: readonly [0, 1];
+    readonly environment: readonly [0, 1];
+    readonly legibility: readonly [0, 1];
+    readonly dimming: readonly [0, 0.5];
+    readonly ink: readonly [0, 1];
+    readonly presence: readonly [0, 0.6];
+    readonly film: readonly [0, 900];
+};
+type VireGlassNumericKey = keyof typeof MATERIAL_RANGES;
+/** Radius over which the LOCAL backdrop lightness is taken, dp. Not per-pixel: otherwise the
+ *  glass chases individual strokes and a halo appears around letters beneath it. */
+declare const ADAPT_RADIUS = 22;
+/** Lens dimming on product surfaces — a flat fill over the backdrop. */
+declare const PRODUCT_DIM = 0.2;
+/** The values the shaders need. Assembled from the material, never set by hand. */
+type VireGlassOptics = {
+    blur: number;
+    refraction: number;
+    refractionScale: number;
+    /** Bevel width in dp — an absolute property of the medium. */
+    bevelDp: number;
+    /** Radius over which the rim gathers light around the element. */
+    gatherRadiusDp: number;
+    fresnel: number;
+    fresnelPower: number;
+    specular: number;
+    specularPower: number;
+    dispersion: number;
+    tint: VireGlassTint;
+    tintStrength: number;
+    edgeDensity: number;
+    environment: number;
+    legibility: number;
+    /** Dimming of the content under the glass — the very layer of the Clear variant. */
+    dimming: number;
+    ink: number;
+    /** Minimum presence of the element against the backdrop — in units of lightness. */
+    presence: number;
+    adaptRadius: number;
+    bodyDensity: number;
+    edgeLight: number;
+    /** Film thickness, nm — passed straight to the shader: the path difference is computed in the
+     *  same units. */
+    film: number;
+    /** Strength of reflection iridescence. */
+    iridescence: number;
+    /** Strength of the edge diffraction fringes. */
+    diffraction: number;
+    /** How much the body is tinted by the color of its surroundings. */
+    colorPickup: number;
+    /** Index of refraction: the shader computes ray bending from it via Snell's law. */
+    ior: number;
+    /** Plate thickness, dp — before the correction for element size. */
+    thicknessDp: number;
+    /** Spread of the index between the red and blue channels — dispersion. */
+    iorSpread: number;
+};
+declare const VIREGLASS_MATERIAL_V4: VireGlassMaterial;
+/**
+ * Glass, not water. v4's index of refraction, 1.33, is water: almost no reflection at the rim,
+ * almost no dispersion, 2% magnification. On screen that surface honestly reads as "nothing much",
+ * and it was being mistaken for glass that wasn't rendering at all.
+ *
+ * 1.5 is ordinary glass. The effects follow from it on their own: reflection at the rim twice as
+ * strong, dispersion one and a half times, ambient color pickup at its ceiling. Thickness is
+ * raised a little too: it drives magnification, but absorption comes along with it, and
+ * absorption is blackness.
+ */
+declare const VIREGLASS_MATERIAL_V5: VireGlassMaterial;
+/**
+ * Frosted sheet glass. The sheet sits over a LIVE screen, and it can't be transparent: transport
+ * buttons and progress used to read right through it — the layout looked broken. Dimming doesn't
+ * fix this (a flat scrim over a sharp picture doesn't hide it), so roughness is raised instead: it
+ * drives `u_frost`, a floor on backdrop blur that the adaptive-blur ceiling doesn't reach.
+ */
+declare const VIREGLASS_SHEET_MATERIAL: VireGlassMaterial;
+/** The product's material. Consumers use this, not a specific version by name. */
+/**
+ * Glass under large text (the lyrics panel in the player).
+ *
+ * The product material with NO change to optics — only `legibility` is raised. That's exactly its
+ * reason to exist: "text on me must stay readable." It adds density locally — denser over light
+ * and busy backdrops, more transparent over an even dark one.
+ *
+ * A dedicated thick material (thickness 52, ior 1.58) used to sit here and was removed: medium
+ * absorption grows with thickness, and the panel picked up a black fringe around its perimeter —
+ * a sooty plate instead of glass. Don't turn thickness into a legibility knob; that's what
+ * `legibility` is for.
+ */
+declare const VIREGLASS_LYRICS_MATERIAL: VireGlassMaterial;
+/**
+ * Glass for controls — buttons, tiles, anything that gets pressed.
+ *
+ * THICK AND CLEAR, not the baseline: wider bevel, thickness up by half, higher index of
+ * refraction and almost no roughness. Baseline glass is a lens over a calm backdrop; a control has
+ * to read as an object you can pick up, and that's not done by a fill but by volume: a wide bevel
+ * gives the rim something to catch, and thickness gives it depth.
+ *
+ * Thickness is set by BUILDUP AT THE RIM: on the reference control the stripe image under the
+ * element bulges there by a factor of 1.85; ours came out at 1.36 at 30. Saturation sets in around
+ * 44, and any extra thickness past that only adds absorption — hence 44, not more.
+ *
+ * It also drags `tintStrength` (= `absorption(thickness)`) along with it, and on the path WITHOUT
+ * a native lens that sets body density: there the element is denser by 2.4 percentage points. On
+ * the web the surface has no body at all; the effect only shows on Android below 13.
+ *
+ * `presence` is raised for the same reason: a piece of background is allowed to disappear over a
+ * uniform canvas, a control isn't — it has to be visible before it's been tapped.
+ *
+ * IMPORTANT about size. The bevel is specified by the medium in dp and doesn't depend on the
+ * element's size, but the geometry clamps it to half the smaller half-size (`MAX_BEVEL_FRACTION`).
+ * On a 52 dp button that's 13 instead of 16 — a small element made of this glass ends up being
+ * bevel all the way through. That's by design: a small piece of thick glass is supposed to look
+ * like a lens, not a slab.
+ */
+declare const VIREGLASS_CONTROL_MATERIAL: VireGlassMaterial;
+declare const VIREGLASS_MATERIAL: VireGlassMaterial;
+/**
+ * An element that CARRIES app ink (an icon, a line of text, cover art) has to keep it legible —
+ * that's the reason `legibility` exists. An element with no ink has nothing to separate lightness
+ * from, so the requirement is turned off for it: the model just promises it plain transparent
+ * glass.
+ *
+ * The rule lives here, not with the consumer: otherwise the same icon button would get different
+ * legibility on the web and on Android.
+ */
+declare function materialForInk(material: VireGlassMaterial, carriesInk: boolean): VireGlassMaterial;
+/**
+ * The transparent material variant (Clear). It has no adaptation — the glass stays consistently
+ * more transparent, content beneath it shows through almost as-is, and legibility of the ink is
+ * held by the dimming layer instead. Fit only where the reference's three conditions hold: the
+ * element sits over media, the content can tolerate dimming, and the ink over it is large and
+ * bright.
+ */
+declare const VIREGLASS_CLEAR_MATERIAL: VireGlassMaterial;
+/**
+ * ACTIVE STATE as a state of the MEDIUM, not a highlight drawn over it.
+ *
+ * An active element is denser, clearer glass: higher index of refraction, thicker body, wider
+ * bevel, less roughness. A bright rim, a strong highlight and greater presence all follow from
+ * these causes on their own — assembling them separately would produce a state that doesn't occur
+ * in real glass.
+ *
+ * `environment` is deliberately left untouched here. It sets how much the body is tinted by
+ * what's beneath it, and at full strength an active button over cover art turned into a colored
+ * blob: the state read as "smudged" rather than "selected." A state indicator must not depend on
+ * the backdrop — otherwise any image sliding underneath the element would fake it.
+ */
+declare function activeMaterial(material: VireGlassMaterial, on: number): VireGlassMaterial;
+declare function resolveMaterial(patch?: Partial<VireGlassMaterial>): VireGlassMaterial;
+/** Causes → effects. All of the transition's physics lives in `optics.ts`. */
+declare function resolveOptics(patch?: Partial<VireGlassMaterial>): VireGlassOptics;
+/**
+ * Frozen snapshots of the EFFECTS from the previous model. Kept as reference points until v4
+ * settles: they can't be converted to causes — some of the values are internally inconsistent
+ * (exactly why the move was made in the first place), and any "equivalent" material would be a
+ * lie.
+ */
+declare const LEGACY_OPTICS: {
+    readonly 'v3-manual': {
+        readonly blur: 4.32;
+        readonly refraction: 0.49;
+        readonly refractionScale: 1.05;
+        readonly bevelDp: 12.6;
+        readonly gatherRadiusDp: 40;
+        readonly fresnel: 0.77;
+        readonly fresnelPower: 2.86;
+        readonly specular: 0.3;
+        readonly specularPower: 74.58;
+        readonly dispersion: 0.54;
+        readonly tint: {
+            readonly r: 0.4;
+            readonly g: 0.4;
+            readonly b: 0.44;
+        };
+        readonly tintStrength: 0.35;
+        readonly edgeDensity: 1.5;
+        readonly environment: 0.27;
+        readonly legibility: 0.55;
+        readonly dimming: 0;
+        readonly ink: 1;
+        readonly presence: 0;
+        readonly adaptRadius: 22;
+        readonly bodyDensity: 0.14;
+        readonly edgeLight: 0.35;
+        readonly film: 0;
+        readonly iridescence: 0;
+        readonly diffraction: 0;
+        readonly colorPickup: 0;
+        readonly ior: 1.5;
+        readonly thicknessDp: 16;
+        readonly iorSpread: 0;
+    };
+    readonly v2: {
+        readonly blur: 5;
+        readonly refraction: 0.95;
+        readonly refractionScale: 1.34;
+        readonly bevelDp: 14;
+        readonly gatherRadiusDp: 40;
+        readonly fresnel: 0.72;
+        readonly fresnelPower: 2.4;
+        readonly specular: 0.38;
+        readonly specularPower: 46;
+        readonly dispersion: 0.3;
+        readonly tint: {
+            readonly r: 0.4;
+            readonly g: 0.4;
+            readonly b: 0.44;
+        };
+        readonly tintStrength: 0.1;
+        readonly edgeDensity: 3.63;
+        readonly environment: 0;
+        readonly legibility: 0;
+        readonly dimming: 0;
+        readonly ink: 1;
+        readonly presence: 0;
+        readonly adaptRadius: 22;
+        readonly bodyDensity: 0.14;
+        readonly edgeLight: 0.35;
+        readonly film: 0;
+        readonly iridescence: 0;
+        readonly diffraction: 0;
+        readonly colorPickup: 0;
+        readonly ior: 1.5;
+        readonly thicknessDp: 16;
+        readonly iorSpread: 0;
+    };
+    readonly v1: {
+        readonly blur: 12;
+        readonly refraction: 0.55;
+        readonly refractionScale: 1.14;
+        readonly bevelDp: 10;
+        readonly gatherRadiusDp: 40;
+        readonly fresnel: 0.5;
+        readonly fresnelPower: 3.2;
+        readonly specular: 0.42;
+        readonly specularPower: 58;
+        readonly dispersion: 0.22;
+        readonly tint: {
+            readonly r: 0.4;
+            readonly g: 0.4;
+            readonly b: 0.44;
+        };
+        readonly tintStrength: 0.16;
+        readonly edgeDensity: 3.63;
+        readonly environment: 0;
+        readonly legibility: 0;
+        readonly dimming: 0;
+        readonly ink: 1;
+        readonly presence: 0;
+        readonly adaptRadius: 22;
+        readonly bodyDensity: 0.14;
+        readonly edgeLight: 0.35;
+        readonly film: 0;
+        readonly iridescence: 0;
+        readonly diffraction: 0;
+        readonly colorPickup: 0;
+        readonly ior: 1.5;
+        readonly thicknessDp: 16;
+        readonly iorSpread: 0;
+    };
+};
+type LegacyOpticsName = keyof typeof LEGACY_OPTICS;
+declare const LEGACY_NAMES: LegacyOpticsName[];
+/** Material presets: points in the space of CAUSES, not a set of ready-made effects. */
+declare const MATERIAL_PRESETS: {
+    readonly water: VireGlassMaterial;
+    readonly glass: {
+        readonly ior: 1.45;
+        readonly thickness: 25;
+        readonly bevel: 12.6;
+        readonly roughness: 0.17;
+        readonly environment: number;
+        readonly legibility: number;
+        readonly dimming: number;
+        readonly ink: number;
+        readonly presence: number;
+        readonly film: number;
+    };
+    readonly crystal: {
+        readonly ior: 1.7;
+        readonly thickness: 30;
+        readonly bevel: 16;
+        readonly roughness: 0.02;
+        readonly environment: number;
+        readonly legibility: number;
+        readonly dimming: number;
+        readonly ink: number;
+        readonly presence: number;
+        readonly film: number;
+    };
+    readonly frosted: {
+        readonly roughness: 0.55;
+        readonly ior: number;
+        readonly thickness: number;
+        readonly bevel: number;
+        readonly environment: number;
+        readonly legibility: number;
+        readonly dimming: number;
+        readonly ink: number;
+        readonly presence: number;
+        readonly film: number;
+    };
+    readonly thick: {
+        readonly thickness: 48;
+        readonly bevel: 22;
+        readonly ior: number;
+        readonly roughness: number;
+        readonly environment: number;
+        readonly legibility: number;
+        readonly dimming: number;
+        readonly ink: number;
+        readonly presence: number;
+        readonly film: number;
+    };
+    readonly thin: {
+        readonly thickness: 4;
+        readonly bevel: 3;
+        readonly ior: number;
+        readonly roughness: number;
+        readonly environment: number;
+        readonly legibility: number;
+        readonly dimming: number;
+        readonly ink: number;
+        readonly presence: number;
+        readonly film: number;
+    };
+    readonly iridescent: {
+        readonly ior: 1.5;
+        readonly thickness: 8;
+        readonly bevel: 6;
+        readonly film: 620;
+        readonly roughness: number;
+        readonly environment: number;
+        readonly legibility: number;
+        readonly dimming: number;
+        readonly ink: number;
+        readonly presence: number;
+    };
+};
+type MaterialPresetName = keyof typeof MATERIAL_PRESETS;
+declare const PRESET_NAMES: MaterialPresetName[];
+declare const EFFECTS: readonly ["backdrop", "blur", "refraction", "fresnel", "bevel", "specular", "dispersion", "tint", "environment", "legibility", "interference", "diffraction"];
+type VireGlassEffect = (typeof EFFECTS)[number];
+type VireGlassToggles = Record<VireGlassEffect, boolean>;
+declare const ALL_EFFECTS_ON: VireGlassToggles;
+/**
+ * A toggle zeroes out an EFFECT, it isn't a branch in the shader: the ON/OFF comparison runs on
+ * one shader variant, otherwise two different programs would be getting compared. It operates on
+ * optics, not on the material: a cause can't be zeroed out — it drags half a dozen effects along
+ * with it. `backdrop` isn't handled by a toggle here: it decides whether to mount the BlurView at
+ * all.
+ */
+declare function applyToggles(optics: VireGlassOptics, toggles?: Partial<VireGlassToggles>): VireGlassOptics;
+/** Order = the `u_debug` value in both shaders. Bench-only. */
+declare const DEBUG_MODES: readonly ["normal", "sdf", "mask", "edge", "fresnel", "refraction", "backdrop", "specular", "dispersion", "normals", "spectral", "adapt", "probe"];
+type VireGlassDebugMode = (typeof DEBUG_MODES)[number];
+declare function debugIndex(mode: VireGlassDebugMode): number;
+
+export { ADAPT_RADIUS as A, DEBUG_MODES as D, EFFECTS as E, LEGACY_NAMES as L, MATERIAL_PRESETS as M, PRESET_NAMES as P, type VireGlassOptics as V, ALL_EFFECTS_ON as a, LEGACY_OPTICS as b, type LegacyOpticsName as c, MATERIAL_RANGES as d, type MaterialPresetName as e, PRODUCT_DIM as f, VIREGLASS_CLEAR_MATERIAL as g, VIREGLASS_CONTROL_MATERIAL as h, VIREGLASS_LYRICS_MATERIAL as i, VIREGLASS_MATERIAL as j, VIREGLASS_MATERIAL_V4 as k, VIREGLASS_MATERIAL_V5 as l, VIREGLASS_SHEET_MATERIAL as m, type VireGlassDebugMode as n, type VireGlassEffect as o, type VireGlassMaterial as p, type VireGlassNumericKey as q, type VireGlassTint as r, type VireGlassToggles as s, activeMaterial as t, applyToggles as u, debugIndex as v, materialForInk as w, resolveMaterial as x, resolveOptics as y };