vireglass 1.0.0 → 2.1.0

package/README.md

@@ -2,8 +2,9 @@
 
 A liquid glass material for interfaces, derived from optics rather than assembled from effects.
 
-One material model, one shader source, two render targets: **WebGL2** in the browser and
-**AGSL** on Android. Apache-2.0.
+One material model, three render targets: **WebGL2** and **live DOM** in the browser, **AGSL** on
+Android. The DOM target refracts the page itself — real elements, real text, no canvas — so glass
+can go over content a renderer never drew. Apache-2.0.
 
 ```bash
 npm install vireglass
@@ -83,10 +84,72 @@ renderer.render({
 `render` also returns one backdrop probe per element — mean lightness, 10th/90th percentiles
 and variegation of what lies under it. That is what the adaptation layer reads.
 
-> **WebGL does not see the DOM.** The lens refracts only what the renderer drew itself, which is
-> why you hand it a `scene` callback that rasterises your backdrop into a 2D canvas. Glass over
-> live HTML is not supported in this release. If that is what you came for, this package does
-> not do it yet.
+> **WebGL does not see the DOM**, so this renderer refracts only what it drew itself — hence the
+> `scene` callback. For glass over your actual page, use `vireglass/dom` below.
+
+## Live DOM
+
+```ts
+import { attachGlass } from 'vireglass/dom';
+
+const glass = attachGlass(document.querySelector('.player'), {
+  material: MATERIAL_PRESETS.glass,
+});
+// glass.update() after a scroll or a theme change, glass.destroy() on unmount
+```
+
+The element now refracts the real page behind it. No canvas, no duplicate render of your UI.
+
+It works by handing `backdrop-filter` an SVG filter whose `feDisplacementMap` bends the backdrop
+along a map derived from the same material model the other renderers use. The browser never gives
+the page's pixels to script — that boundary is what stops a page reading your cross-origin frames
+and visited links — so the displacement happens inside the compositor, where the pixels already are.
+
+It carries the material, not a corner of it: refraction with per-channel dispersion, the rim with
+its two opposing arcs and dark edge, the adaptive shadow, the body under legibility and presence,
+and the finger response — press, drag, the release wave and the rise into glass.
+
+```ts
+glass.setMorph({ smoothing: 34, shape: { offsetX: 150, offsetY: -78, width: 170, height: 92, cornerRadius: 28 } });
+```
+
+Two shapes joined through the smooth union — §5's merging and splitting. What the shapes mean is
+your choreography; the material only knows how two silhouettes join.
+
+`attachGlass` writes CSS custom properties you can use directly:
+
+| | |
+|---|---|
+| `--vireglass-ink-color` | ink colour for this backdrop, already resolved |
+| `--vireglass-body-color` | the glass body: density from the model, hue from the surroundings |
+| `--vireglass-tint-color` | ambient colour alone |
+| `--vireglass-rim`, `--vireglass-rim-width` | the hairline's gradient, applied for you |
+| `--vireglass-shadow` | the adaptive shadow, also written to `box-shadow` unless you opt out |
+| `--vireglass-radius`, `--vireglass-radius-min` | for concentric children (§11) |
+| `--vireglass-ink`, `--vireglass-tint`, `--vireglass-body-density` | the model's raw numbers |
+
+The three system accessibility settings are read from the browser's own media queries and
+followed while the page is open — reduced transparency frosts the glass, increased contrast takes
+the element by its silhouette, reduced motion holds it still. A system setting outranks the
+material preset and the user's own clarity slider (`scale`), because the user needs contrast more
+than they need the look.
+
+Three things to know before you reach for it:
+
+- **It renders the whole material.** Refraction with per-channel dispersion, the rim with its two
+  opposing arcs and dark edge, the adaptive shadow, the body under legibility and presence, the
+  finger response, and the spectral edge — diffraction and interference baked into a hue map and
+  multiplied in, since a filter graph cannot evaluate a function per pixel but can multiply by an
+  image.
+
+- **The refraction is Chromium-only today.** Firefox does not support a filter reference in
+  `backdrop-filter` and has closed the request as not planned; Safari does not yet, though WebKit
+  has patches in flight. Elsewhere `attachGlass` falls back to blur, saturation and tint from the
+  same optics — detected by measurement, never by user-agent string.
+- **There is no pixel probe, so adaptation reads declared styles.** The grid under the element is
+  sampled through `elementsFromPoint` and the background stack is composited. That is exact for
+  colour-defined surfaces and blind to images, video and canvas — pass your own `sample` there,
+  since your app already knows its cover-art accent.
 
 ## Android / React Native
 
@@ -157,9 +220,13 @@ preference; `applyGlassScale` gives that preference its own axis, ultra clear to
 
 ```bash
 npm run typecheck
-npm test            # 122 tests
-npm run check:glsl  # both shaders compile and link as GLSL ES 3.0
+npm test
+npm run check:glsl   # both shaders compile and link as GLSL ES 3.0
 npm run check:optics
+npm run check:law    # every calibrated number is in src/law.ts, cited or named unmeasured
+npm run check:dom    # a real browser: the glass bends live DOM, and only where it should
+npm run check:package # packs, installs into an empty project, loads every entry point
+npm run check:readme  # every name the documentation tells you to import exists
 ```
 
 `check:optics` is the interesting one. It renders the material over a sweep of backdrops and
@@ -171,7 +238,9 @@ canvas, and that the rim gathers what is behind it.
 
 ## Limits — read these before adopting
 
-- **No glass over live DOM on the web.** See above.
+- **Glass over live DOM refracts in Chromium only**, and falls back to blur elsewhere. Its
+  adaptation reads declared styles rather than pixels, so images and video need a supplied
+  `sample`. See *Live DOM* above.
 - **Refraction needs Android 13+** (`RenderEffect`). Below that it degrades to an affine
   magnifier: a loupe, not a lens.
 - **No iOS.** There is no public API for reading what is behind a view.
@@ -200,6 +269,8 @@ canvas, and that the rim gathers what is behind it.
 | `docs/adr-001-rendering.md` | the rendering architecture decision and its evidence |
 | `docs/platform-parity.md` | how web and Android are kept numerically in agreement |
 | `docs/benchmarks.md` | measurement protocol, device, numbers |
+| `docs/dom.md` | the DOM renderer: the technique, what it renders, what it costs |
+| `docs/law.md` | where every calibrated number lives, and which ones nobody has measured |
 | `docs/material-lab.md` | selected entries from the experiment journal |
 
 ## Calibration
@@ -209,6 +280,9 @@ sessions 219 and 356 and related design talks — and the documentation cites th
 timestamp so the claims can be checked. No Apple code, assets or footage is included in or
 distributed with this package.
 
+Every calibrated number lives in `src/law.ts` with its provenance, and `check:law` names the ones
+that have none: **42 of 120** today. See [`docs/law.md`](docs/law.md).
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/dist/adapters-BfeAopGO.d.ts

@@ -0,0 +1,154 @@
+import { V as VireGlassGeometry } from './geometry-GvXtt-_S.js';
+import { V as VireGlassOptics, o as VireGlassDebugMode } from './material-CnUmdKg1.js';
+
+/** Smooth union with a second shape — bench morphing experiment only. */
+type VireGlassMorph = {
+    offsetX: number;
+    offsetY: number;
+    width: number;
+    height: number;
+    cornerRadius: number;
+    /** Seam smoothing radius in dp; 0 turns the second shape off. */
+    smoothing: number;
+};
+/** Surface response to a finger: the field around the touch point deforms, not the shape's
+ *  bounding box (`vgTouchWarp` in `sdf.ts`). Lengths in dp; `radius` = 0 turns the response off
+ *  entirely. */
+type VireGlassTouch = {
+    x: number;
+    y: number;
+    pullX: number;
+    pullY: number;
+    press: number;
+    radius: number;
+    waveAmp: number;
+    wavePhase: number;
+};
+/** Tinted glass for the primary action (M 16:08). Color is RGB 0…1. */
+type VireGlassAccent = {
+    color: readonly [number, number, number];
+    amount?: number;
+};
+/** Default tint fraction: the color reads, but content beneath it is still visible. */
+declare const ACCENT_AMOUNT: 0.8;
+/** Magnification at the flat center. Kept separate from the uniform channel: it's also used by
+ *  the fallback below Android 13, where there's no RuntimeShader and only an affine magnifier is
+ *  left. */
+declare const lensMagnify: (o: VireGlassOptics) => number;
+/** Props for the native view. Besides the uniform channel, only what the view uses itself lives
+ *  here: the shader source and the visible glass's size (the probe rectangle is taken from it). */
+declare function toLensProps(optics: VireGlassOptics, geometry: VireGlassGeometry, density: number, options?: {
+    debug?: VireGlassDebugMode;
+    morph?: VireGlassMorph;
+    /** Third shape of the fused body; a zero size turns it off. */
+    morph2?: VireGlassMorph;
+    groupProbe?: number[];
+    touch?: VireGlassTouch;
+    /** Progress fraction, 0…1: to the left of the boundary the element is active. `undefined` means no progress. */
+    progress?: number;
+    /** Key light direction in screen space; defaults to the light at rest. */
+    light?: readonly [number, number];
+    /** 0…1: the lens builds up as the element appears — instead of a plain fade. */
+    appear?: number;
+    /** Tint for the primary action: the glass color and the fraction it lays over the content. */
+    accent?: VireGlassAccent;
+}): {
+    uniformNames: string[];
+    uniformSizes: number[];
+    uniformValues: number[];
+    shaderSource: string;
+    glassWidth: number;
+    glassHeight: number;
+};
+/** Static part of the surface uniforms. Dynamics (gesture, press, light) get mixed in inside the
+ *  component's worklet — the adapter must stay an ordinary function. */
+declare function toSurfaceUniforms(optics: VireGlassOptics, geometry: VireGlassGeometry, options?: {
+    debug?: VireGlassDebugMode;
+    morph?: VireGlassMorph;
+    /** Third shape of the fused body; a zero size turns it off. */
+    morph2?: VireGlassMorph;
+    dragLimit?: number;
+    shadow?: number;
+    /** Average ambient color around the element: light from it bleeds into the shadow (reference 219 @8:22). */
+    ambient?: readonly [number, number, number];
+    /** The lens draws the glass body — the surface is left with the highlight, shadow and icon. */
+    bodyInLens?: boolean;
+    touch?: VireGlassTouch;
+    /** Progress fraction, 0…1: to the left of the boundary the element is active. `undefined` means no progress. */
+    progress?: number;
+    /** 0…1: the element is appearing — shadow and ink build up together with the lens. */
+    appear?: number;
+    /** 0 — the element sinks in under the finger, 1 — it rises into glass (reference §5). */
+    lift?: number;
+}): {
+    u_center: number[];
+    u_halfSize: number[];
+    u_corner: number;
+    u_bevel: number;
+    u_thickness: number;
+    u_morphOffset: number[];
+    u_morphHalf: number[];
+    u_morphCorner: number;
+    u_morphK: number;
+    u_morph2Offset: number[];
+    u_morph2Half: number[];
+    u_morph2Corner: number;
+    u_edgeDensity: number;
+    u_dispersion: number;
+    u_refraction: number;
+    u_tint: number[];
+    u_shadow: number;
+    u_ambient: readonly [number, number, number];
+    u_shadowReach: number;
+    u_touch: number[];
+    u_pull: number[];
+    u_touchPress: number;
+    u_touchRadius: number;
+    u_wave: number[];
+    u_presence: number;
+    u_progress: number;
+    u_appear: number;
+    u_lift: number;
+    u_debug: number;
+};
+/**
+ * Surface fields that are LENGTHS: the adapter's contract is specified in dp, and on the web each
+ * one of them has to be multiplied by screen density. The list lives here rather than in the
+ * renderer, where it used to be a dozen and a half manual multiplications in a row: a missed
+ * field there was only caught by eye, and the miss isn't visible everywhere — at density 1,
+ * multiplying is indistinguishable from not doing it.
+ */
+type SurfaceUniforms = ReturnType<typeof toSurfaceUniforms>;
+declare const SURFACE_LENGTH_UNIFORMS: readonly ["u_halfSize", "u_corner", "u_bevel", "u_morphOffset", "u_morphHalf", "u_morphCorner", "u_morphK", "u_morph2Offset", "u_morph2Half", "u_morph2Corner", "u_shadowReach", "u_touch", "u_pull", "u_touchRadius"];
+/**
+ * Surface uniforms in device pixels. Android draws in dp and calls the adapter as-is; the web
+ * needs this conversion. `u_center` isn't part of it: the renderer knows the element's center on
+ * its own.
+ */
+declare function toDeviceSurfaceUniforms(raw: SurfaceUniforms, density: number): SurfaceUniforms;
+/** Key light direction in screen coordinates, for when the orientation response is off. */
+declare const REST_LIGHT: readonly [number, number];
+/** Uniforms the component mixes in inside the worklet (press, active, light direction) and via
+ *  the icon layer. Listed here so a test can check the shader contract's completeness without
+ *  importing the component itself (it pulls in Skia and doesn't come up in a node environment). */
+declare const DYNAMIC_UNIFORMS: readonly ["u_press", "u_active"];
+declare const ICON_UNIFORMS: readonly ["u_iconOn", "u_iconScale", "u_inkIdle", "u_inkActive"];
+/** App-colored overlay layer on the glass. The `u_overlay` sampler shares its contract with the
+ *  ink mask and is sampled at the SAME coordinate — otherwise deformation would carry them apart. */
+declare const OVERLAY_UNIFORMS: readonly ["u_overlayOn"];
+declare function morphBetween(a: VireGlassGeometry, b: VireGlassGeometry, offsetX: number, offsetY: number, t: number): VireGlassMorph | undefined;
+/**
+ * MITOSIS: the second shape grows OUT OF the first and travels to its place, instead of appearing
+ * beside it at full size. A menu coming out of its button, a control dividing into segments.
+ *
+ * `morphBetween` is the other half — two shapes that are both already where they belong, fusing
+ * into one body — and run backwards it is meiosis, the neck thinning until it breaks. What neither
+ * of them may do is pop: at any `t` above zero this returns one continuous body, because that is
+ * the whole of what the reference says a material transition is.
+ *
+ * The choreography stays the host's: what the shapes MEAN is the app's business. How a silhouette
+ * emerges from another silhouette is the material's, the same way the spring under a finger is.
+ */
+declare function morphOutOf(source: VireGlassGeometry, target: VireGlassGeometry, offsetX: number, offsetY: number, t: number): VireGlassMorph | undefined;
+
+export { ACCENT_AMOUNT as A, DYNAMIC_UNIFORMS as D, ICON_UNIFORMS as I, OVERLAY_UNIFORMS as O, REST_LIGHT as R, SURFACE_LENGTH_UNIFORMS as S, type VireGlassAccent as V, type SurfaceUniforms as a, type VireGlassMorph as b, type VireGlassTouch as c, morphOutOf as d, toLensProps as e, toSurfaceUniforms as f, lensMagnify as l, morphBetween as m, toDeviceSurfaceUniforms as t };

package/dist/adapters-DugC6Qri.d.cts

@@ -0,0 +1,154 @@
+import { V as VireGlassGeometry } from './geometry-RhKd7CM5.cjs';
+import { V as VireGlassOptics, o as VireGlassDebugMode } from './material-CnUmdKg1.cjs';
+
+/** Smooth union with a second shape — bench morphing experiment only. */
+type VireGlassMorph = {
+    offsetX: number;
+    offsetY: number;
+    width: number;
+    height: number;
+    cornerRadius: number;
+    /** Seam smoothing radius in dp; 0 turns the second shape off. */
+    smoothing: number;
+};
+/** Surface response to a finger: the field around the touch point deforms, not the shape's
+ *  bounding box (`vgTouchWarp` in `sdf.ts`). Lengths in dp; `radius` = 0 turns the response off
+ *  entirely. */
+type VireGlassTouch = {
+    x: number;
+    y: number;
+    pullX: number;
+    pullY: number;
+    press: number;
+    radius: number;
+    waveAmp: number;
+    wavePhase: number;
+};
+/** Tinted glass for the primary action (M 16:08). Color is RGB 0…1. */
+type VireGlassAccent = {
+    color: readonly [number, number, number];
+    amount?: number;
+};
+/** Default tint fraction: the color reads, but content beneath it is still visible. */
+declare const ACCENT_AMOUNT: 0.8;
+/** Magnification at the flat center. Kept separate from the uniform channel: it's also used by
+ *  the fallback below Android 13, where there's no RuntimeShader and only an affine magnifier is
+ *  left. */
+declare const lensMagnify: (o: VireGlassOptics) => number;
+/** Props for the native view. Besides the uniform channel, only what the view uses itself lives
+ *  here: the shader source and the visible glass's size (the probe rectangle is taken from it). */
+declare function toLensProps(optics: VireGlassOptics, geometry: VireGlassGeometry, density: number, options?: {
+    debug?: VireGlassDebugMode;
+    morph?: VireGlassMorph;
+    /** Third shape of the fused body; a zero size turns it off. */
+    morph2?: VireGlassMorph;
+    groupProbe?: number[];
+    touch?: VireGlassTouch;
+    /** Progress fraction, 0…1: to the left of the boundary the element is active. `undefined` means no progress. */
+    progress?: number;
+    /** Key light direction in screen space; defaults to the light at rest. */
+    light?: readonly [number, number];
+    /** 0…1: the lens builds up as the element appears — instead of a plain fade. */
+    appear?: number;
+    /** Tint for the primary action: the glass color and the fraction it lays over the content. */
+    accent?: VireGlassAccent;
+}): {
+    uniformNames: string[];
+    uniformSizes: number[];
+    uniformValues: number[];
+    shaderSource: string;
+    glassWidth: number;
+    glassHeight: number;
+};
+/** Static part of the surface uniforms. Dynamics (gesture, press, light) get mixed in inside the
+ *  component's worklet — the adapter must stay an ordinary function. */
+declare function toSurfaceUniforms(optics: VireGlassOptics, geometry: VireGlassGeometry, options?: {
+    debug?: VireGlassDebugMode;
+    morph?: VireGlassMorph;
+    /** Third shape of the fused body; a zero size turns it off. */
+    morph2?: VireGlassMorph;
+    dragLimit?: number;
+    shadow?: number;
+    /** Average ambient color around the element: light from it bleeds into the shadow (reference 219 @8:22). */
+    ambient?: readonly [number, number, number];
+    /** The lens draws the glass body — the surface is left with the highlight, shadow and icon. */
+    bodyInLens?: boolean;
+    touch?: VireGlassTouch;
+    /** Progress fraction, 0…1: to the left of the boundary the element is active. `undefined` means no progress. */
+    progress?: number;
+    /** 0…1: the element is appearing — shadow and ink build up together with the lens. */
+    appear?: number;
+    /** 0 — the element sinks in under the finger, 1 — it rises into glass (reference §5). */
+    lift?: number;
+}): {
+    u_center: number[];
+    u_halfSize: number[];
+    u_corner: number;
+    u_bevel: number;
+    u_thickness: number;
+    u_morphOffset: number[];
+    u_morphHalf: number[];
+    u_morphCorner: number;
+    u_morphK: number;
+    u_morph2Offset: number[];
+    u_morph2Half: number[];
+    u_morph2Corner: number;
+    u_edgeDensity: number;
+    u_dispersion: number;
+    u_refraction: number;
+    u_tint: number[];
+    u_shadow: number;
+    u_ambient: readonly [number, number, number];
+    u_shadowReach: number;
+    u_touch: number[];
+    u_pull: number[];
+    u_touchPress: number;
+    u_touchRadius: number;
+    u_wave: number[];
+    u_presence: number;
+    u_progress: number;
+    u_appear: number;
+    u_lift: number;
+    u_debug: number;
+};
+/**
+ * Surface fields that are LENGTHS: the adapter's contract is specified in dp, and on the web each
+ * one of them has to be multiplied by screen density. The list lives here rather than in the
+ * renderer, where it used to be a dozen and a half manual multiplications in a row: a missed
+ * field there was only caught by eye, and the miss isn't visible everywhere — at density 1,
+ * multiplying is indistinguishable from not doing it.
+ */
+type SurfaceUniforms = ReturnType<typeof toSurfaceUniforms>;
+declare const SURFACE_LENGTH_UNIFORMS: readonly ["u_halfSize", "u_corner", "u_bevel", "u_morphOffset", "u_morphHalf", "u_morphCorner", "u_morphK", "u_morph2Offset", "u_morph2Half", "u_morph2Corner", "u_shadowReach", "u_touch", "u_pull", "u_touchRadius"];
+/**
+ * Surface uniforms in device pixels. Android draws in dp and calls the adapter as-is; the web
+ * needs this conversion. `u_center` isn't part of it: the renderer knows the element's center on
+ * its own.
+ */
+declare function toDeviceSurfaceUniforms(raw: SurfaceUniforms, density: number): SurfaceUniforms;
+/** Key light direction in screen coordinates, for when the orientation response is off. */
+declare const REST_LIGHT: readonly [number, number];
+/** Uniforms the component mixes in inside the worklet (press, active, light direction) and via
+ *  the icon layer. Listed here so a test can check the shader contract's completeness without
+ *  importing the component itself (it pulls in Skia and doesn't come up in a node environment). */
+declare const DYNAMIC_UNIFORMS: readonly ["u_press", "u_active"];
+declare const ICON_UNIFORMS: readonly ["u_iconOn", "u_iconScale", "u_inkIdle", "u_inkActive"];
+/** App-colored overlay layer on the glass. The `u_overlay` sampler shares its contract with the
+ *  ink mask and is sampled at the SAME coordinate — otherwise deformation would carry them apart. */
+declare const OVERLAY_UNIFORMS: readonly ["u_overlayOn"];
+declare function morphBetween(a: VireGlassGeometry, b: VireGlassGeometry, offsetX: number, offsetY: number, t: number): VireGlassMorph | undefined;
+/**
+ * MITOSIS: the second shape grows OUT OF the first and travels to its place, instead of appearing
+ * beside it at full size. A menu coming out of its button, a control dividing into segments.
+ *
+ * `morphBetween` is the other half — two shapes that are both already where they belong, fusing
+ * into one body — and run backwards it is meiosis, the neck thinning until it breaks. What neither
+ * of them may do is pop: at any `t` above zero this returns one continuous body, because that is
+ * the whole of what the reference says a material transition is.
+ *
+ * The choreography stays the host's: what the shapes MEAN is the app's business. How a silhouette
+ * emerges from another silhouette is the material's, the same way the spring under a finger is.
+ */
+declare function morphOutOf(source: VireGlassGeometry, target: VireGlassGeometry, offsetX: number, offsetY: number, t: number): VireGlassMorph | undefined;
+
+export { ACCENT_AMOUNT as A, DYNAMIC_UNIFORMS as D, ICON_UNIFORMS as I, OVERLAY_UNIFORMS as O, REST_LIGHT as R, SURFACE_LENGTH_UNIFORMS as S, type VireGlassAccent as V, type SurfaceUniforms as a, type VireGlassMorph as b, type VireGlassTouch as c, morphOutOf as d, toLensProps as e, toSurfaceUniforms as f, lensMagnify as l, morphBetween as m, toDeviceSurfaceUniforms as t };