vireglass 2.3.1 → 3.0.0

package/dist/web/index.d.cts

@@ -1,6 +1,6 @@
-import { b as VireGlassMorph, c as VireGlassTouch, V as VireGlassAccent } from '../adapters-BOPIRMnL.cjs';
-import { V as VireGlassGeometry } from '../geometry-RhKd7CM5.cjs';
-import { V as VireGlassOptics, o as VireGlassDebugMode } from '../material-CnUmdKg1.cjs';
+import { b as VireGlassMorph, c as VireGlassTouch, V as VireGlassAccent } from '../adapters--bXcGvhW.cjs';
+import { V as VireGlassGeometry } from '../geometry-ip9WSlZv.cjs';
+import { V as VireGlassOptics, o as VireGlassDebugMode } from '../material-D9m1EN47.cjs';
 
 declare const PROBE_GRID_WIDTH = 48;
 declare const PROBE_GRID_HEIGHT = 96;

package/dist/web/index.d.ts

@@ -1,6 +1,6 @@
-import { b as VireGlassMorph, c as VireGlassTouch, V as VireGlassAccent } from '../adapters-B_amRBqc.js';
-import { V as VireGlassGeometry } from '../geometry-GvXtt-_S.js';
-import { V as VireGlassOptics, o as VireGlassDebugMode } from '../material-CnUmdKg1.js';
+import { b as VireGlassMorph, c as VireGlassTouch, V as VireGlassAccent } from '../adapters-BlMhc6pI.js';
+import { V as VireGlassGeometry } from '../geometry-pabkYV7w.js';
+import { V as VireGlassOptics, o as VireGlassDebugMode } from '../material-D9m1EN47.js';
 
 declare const PROBE_GRID_WIDTH = 48;
 declare const PROBE_GRID_HEIGHT = 96;

package/dist/web/index.js

@@ -1,7 +1,7 @@
-import { toGLSL, SURFACE_SHADER } from '../chunk-UDPJLNFW.js';
-import { LENS_SHADER, toLensProps, toSurfaceUniforms, toDeviceSurfaceUniforms, DYNAMIC_UNIFORMS, ICON_UNIFORMS, OVERLAY_UNIFORMS } from '../chunk-V47YU75P.js';
-import { lensPadDp, surfacePadDp, shadowOpacity } from '../chunk-SLRPHDV7.js';
-import '../chunk-MMPK6DCK.js';
+import { toGLSL, SURFACE_SHADER } from '../chunk-RWUR3OV6.js';
+import { LENS_SHADER, toLensProps, toSurfaceUniforms, toDeviceSurfaceUniforms, DYNAMIC_UNIFORMS, ICON_UNIFORMS, OVERLAY_UNIFORMS } from '../chunk-YAN2OK4H.js';
+import { lensPadDp, surfacePadDp, shadowOpacity } from '../chunk-Z4FKYY47.js';
+import '../chunk-CPSIY2DZ.js';
 
 // src/web/gl.ts
 var FULLSCREEN_TRIANGLE_VERTEX_SOURCE = `#version 300 es

package/docs/dom.md

@@ -41,8 +41,8 @@ checks the centre is neutral.
 | §1 refraction, magnification | `feDisplacementMap` along a baked displacement map |
 | §1 dispersion | three displacement passes, one per channel, at the shader's own index shifts |
 | §1 diffraction, §3 interference | one baked hue map, multiplied in by an arithmetic composite |
-| §2 rim light, two arcs, dark edge | a masked conic gradient on `::after`, angles and weights from the lens's key-light lobe |
-| §3 body, legibility, presence | `resolveBody` — the lens's own law, one value per element |
+| §2 rim light, two arcs, dark edge | a masked conic gradient on `::after`: a light line round the whole contour with the lens's key-light lobe on it, over a dark edge; strength from the ambient lightness |
+| §3 body, legibility, presence | `resolveBody` and `bodyLayer` — the lens's own law, composed into one translucent layer per element, painted as `background-color` |
 | §3 ink polarity | `shouldInkBeLight`, the same function every platform uses |
 | §4 adaptive shadow | `box-shadow`, density from `shadowOpacityFrom` |
 | §5 touch, press, drag, wave, rise | `createDeform` driving the same `touchWarp` the shader uses |
@@ -57,6 +57,51 @@ lobe, its exponent, the 0.45 opposing arc and the 0.22 dark edge are the lens's
 spectral hue is baked rather than evaluated, because a filter graph has no way to run a function
 per pixel but can multiply by an image.
 
+## Measured against the reference
+
+The controls of A 2:17 (over dark video), M 2:52 (over sky), A 2:18 (grass), M 18:26 (a flower),
+M 18:30 (the same under reduced transparency) and M 11:58 (text) were cut from the reference frames,
+the control's own footprint filled smoothly from its surround, and a 44 dp circle or capsule of
+`VIREGLASS_CONTROL_MATERIAL` laid over each at device pixel ratio 3, with the footprint's mean colour
+as `sample`. Body and surround are OKLab medians of the rings 0.15 to 0.45 R inside the rim and 0.15
+to 0.55 R outside it; the rim is the brightest of 24 angular bins (90th percentile) over the surround.
+The frames are local and are not in the repository.
+
+Body lightness over the surround (ΔL) and rim over the surround, reference, then 2.3.1, then this
+release:
+
+| control | ref ΔL | 2.3.1 | now | ref rim | 2.3.1 | now |
+|---|---|---|---|---|---|---|
+| A 2:17 skip back | +0.086 | +0.023 | +0.090 | 0.240 | 0.707 | 0.253 |
+| A 2:17 pause | +0.071 | +0.038 | +0.117 | 0.257 | 0.762 | 0.310 |
+| A 2:17 skip forward | +0.045 | +0.027 | +0.114 | 0.268 | 0.796 | 0.320 |
+| A 2:17 Continue | +0.080 | +0.076 | +0.143 | 0.256 | 0.759 | 0.317 |
+| A 2:17 Info | +0.126 | +0.018 | +0.088 | 0.268 | 0.704 | 0.236 |
+| M 2:52 next, over sky | +0.076 | +0.002 | +0.025 | 0.246 | 0.329 | 0.240 |
+| A 2:18 more, over grass (a) | +0.232 | +0.016 | +0.061 | 0.372 | 0.523 | 0.352 |
+| M 18:26 flower (a) | +0.040 | -0.019 | +0.004 | 0.291 | 0.293 | 0.203 |
+| M 18:30 reduced transparency (a) | +0.169 | -0.127 | -0.367 | 0.187 | 0.301 | 0.192 |
+| M 11:58 bar over text (a) | +0.049 | -0.044 | -0.040 | 0.114 | 0.114 | 0.063 |
+
+(a) the backdrop under the control is not in the frame, so the surround is only a guess for it.
+
+The body is lighter than the surround on every smooth row, as in the reference, and within 0.05 of
+it on skip back, pause and Info; skip forward and Continue are 0.07 and 0.06 above, and sky is 0.051
+below. Chroma is within 0.04 of the reference on every row. The rim is within 0.08 on every smooth
+row. The medium's own lift (matte, pull, concentration of light) sets the body now; the control
+material no longer asks for a presence floor on top of it. A presence that brings the sky inside 0.05
+puts two dark rows further out, and the reference's own spread (+0.045 to +0.126 over similar
+backdrops) is wider than the tolerance, so one constant cannot sit inside all of them.
+
+Reduced transparency (M 18:30) is not held to the reference: the backdrop's lightness sits at the
+ink polarity's switch, the ink stays light, and a body at the density that mode asks for goes to its
+pole, a dark plate where the reference is a light one.
+
+The WebGL2 lens and this path were measured on the same flat backdrops (the footprint means above)
+with the same material: body within 0.019 of each other everywhere, rim within 0.021 over dark,
+0.053 over sky and grass and 0.024 over near-white, the lens fainter over light. Both are inside the
+rim tolerance.
+
 ## The probe reads styles, not pixels
 
 Adaptation needs to know what is behind the element, and the same door that stops the lens reading
@@ -68,7 +113,8 @@ Compositing is not optional. Taking the first layer with any alpha at all reads
 exist — over a dark page the ink goes dark and the label disappears.
 
 It is exact for colour-defined surfaces and blind to images, video and iframes. Hosts pass their
-own sample there; an app already knows its cover art's accent.
+own sample there; an app already knows its cover art's accent, and `setSample` changes it later
+without re-attaching.
 
 ## What it costs
 

package/docs/law.md

@@ -42,7 +42,7 @@ It checks three things, and reports a fourth:
 - and it names every unmeasured value, every run — and fails if this page or the README states a
   different number, because a count written out in prose goes stale the moment a value is added.
 
-Today that last line reads **43 of 121**. That is the real state of the model, and it is meant to
+Today that last line reads **51 of 130**. That is the real state of the model, and it is meant to
 be uncomfortable. It was 9 until the constants hiding inside `optics.ts`, `geometry.ts` and
 `touch-response.ts` were brought in — the number did not get worse, the instrument got honest.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vireglass",
-  "version": "2.3.1",
+  "version": "3.0.0",
   "description": "A physically-derived liquid glass material for interfaces. One material model, three render targets: WebGL2, live DOM, and Android AGSL.",
   "license": "Apache-2.0",
   "author": "Danil Kotlaev",

package/src/dom/body.ts

@@ -1,10 +1,10 @@
 // The glass BODY (docs/reference.md §3): how dense the medium has to be over this particular
 // backdrop, and which way it tints.
 //
-// The law is the lens shader's, lines 444–482, ported to one value per element instead of one per
+// The law is the lens shader's, ported to one value per element instead of one per
 // pixel — the DOM path has a single backdrop sample, not a plane. Constants keep their names from
 // the shader so the two stay comparable.
-import { BODY } from '../law';
+import { BODY, MEDIUM } from '../law';
 import type { VireGlassOptics } from '../material';
 
 const {
@@ -14,8 +14,10 @@ const {
   tintLight: TINT_LIGHT,
   groundSpan: GROUND_SPAN,
   busyEdge: BUSY_EDGE,
-  darkSideFrom: DARK_SIDE_FROM,
-  darkSideTo: DARK_SIDE_TO,
+  inkBusyFrom: INK_BUSY_FROM,
+  inkBusyTo: INK_BUSY_TO,
+  inkPoleTo: INK_POLE_TO,
+  presenceDemand: PRESENCE_DEMAND,
   maxDemand: MAX_DEMAND,
 } = BODY;
 
@@ -35,8 +37,22 @@ export type GlassBody = {
   density: number;
   /** Lightness the body tints toward. */
   tintLuma: number;
+  /** The part of the density the ink's legibility asked for, and the pole it asked toward. */
+  need: number;
+  pole: number;
 };
 
+/**
+ * The body is lighter than its surroundings whatever the glyph on it is: glass concentrates light
+ * (M 2:29), and the reference keeps a lighter body under a white glyph over sky as much as over
+ * dark. It goes to the ink's own pole only where the ink's legibility is what holds the density —
+ * or a system setting has raised it past anything a presence floor asks for.
+ */
+function tintFor(density: number, need: number, pole: number): number {
+  const asked = Math.max(clamp(need / Math.max(density, 1e-4), 0, 1), smoothstep(PRESENCE_DEMAND, INK_POLE_TO, density));
+  return mix(TINT_LIGHT, pole, asked);
+}
+
 /**
  * `ink` is POLARITY, 1 light and 0 dark, matching the shader's uniform. The requirements are
  * evaluated at both ends and blended by it — computing at the current polarity alone makes the
@@ -54,11 +70,7 @@ export function resolveBody(optics: VireGlassOptics, sample: BodyBackdrop, ink:
   const mean = clamp(sample.luma, 0, 1);
   const busy = Math.max(sample.busy, 0);
 
-  // Direction of the tint follows the element's AVERAGE lightness, not a local spot: on a
-  // gradient a local threshold cuts a diagonal step across the body.
-  const darkSide = smoothstep(DARK_SIDE_FROM, DARK_SIDE_TO, mean);
-  const away = mix(TINT_LIGHT, TINT_DARK, darkSide);
-  const tintLuma = mix(away, mix(TINT_LIGHT, TINT_DARK, pol), demand);
+  const pole = mix(TINT_LIGHT, TINT_DARK, pol);
 
   // How much medium it takes to push the lightness under the ink past its threshold, measured
   // from whichever edge of the backdrop's spread is closer to the ink — a light ink drowns in a
@@ -68,46 +80,88 @@ export function resolveBody(optics: VireGlassOptics, sample: BodyBackdrop, ink:
   const inkLo = Math.max(mean - edge, 0);
   const needForLight = inkHi > capLight ? clamp((inkHi - capLight) / Math.max(inkHi - TINT_DARK, 1e-4), 0, MAX_DEMAND) : 0;
   const needForDark = inkLo < floorDark ? clamp((floorDark - inkLo) / Math.max(TINT_LIGHT - inkLo, 1e-4), 0, MAX_DEMAND) : 0;
-  const needForInk = mix(needForDark, needForLight, pol) * demand;
+  // Over a flat backdrop the ink asks for nothing: polarity flips before it drowns. It is spread
+  // under the ink that the body has to answer.
+  const structured = smoothstep(INK_BUSY_FROM, INK_BUSY_TO, busy);
+  const needForInk = mix(needForDark, needForLight, pol) * demand * structured;
 
   // Fine texture the body has to stop being a window for, the same way roughness does it.
   const ground = busy * optics.legibility * GROUND_SPAN;
 
-  return { density: Math.max(Math.max(optics.bodyDensity, ground), needForInk), tintLuma };
+  const density = Math.max(Math.max(optics.bodyDensity, ground), needForInk);
+  return { density, tintLuma: tintFor(density, needForInk, pole), need: needForInk, pole };
 }
 
 /**
  * PRESENCE (§3): over a uniform backdrop there is nothing to refract and the glass honestly
- * disappears — right for a piece of background, wrong for a control. It is a MINIMUM, not an
- * addition, so a body that already stands apart is left alone.
+ * disappears — right for a piece of background, wrong for a control. It is a MINIMUM on the
+ * density, toward light whatever the ink, and it does not read the backdrop: the lift it gives is
+ * `presence` times the room left under the light pole, so it fades out as the room does and has no
+ * step anywhere on the scale.
+ */
+export function withPresence(body: GlassBody, optics: VireGlassOptics, _sample?: BodyBackdrop): GlassBody {
+  if (optics.presence <= 0) return body;
+  const density = Math.max(body.density, Math.min(optics.presence / TINT_LIGHT, PRESENCE_DEMAND));
+  return { ...body, density, tintLuma: tintFor(density, body.need, body.pole) };
+}
+
+export type BodyLayer = {
+  /** Straight (not premultiplied) colour, 0…1 per channel. */
+  r: number;
+  g: number;
+  b: number;
+  alpha: number;
+};
+
+/** The lens's `vgHue`: colour without lightness, and white below the lightness it has none at. */
+function hueOf(c: readonly [number, number, number]): [number, number, number] {
+  const l = 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+  if (l < 0.02) return [1, 1, 1];
+  return [clamp(c[0] / l, 0, 2), clamp(c[1] / l, 0, 2), clamp(c[2] / l, 0, 2)];
+}
+
+/**
+ * The body as ONE translucent layer over the backdrop, which is the form the DOM can draw it in.
  *
- * The direction is the body's own. The previous version decided "lighter over dark, darker over
- * light" from the backdrop alone, and then, when the body disagreed, clamped `tintLuma` to the
- * backdrop's mean — the one value that separates from nothing. Light ink over a dark backdrop puts
- * the body at 0.07 against a backdrop of 0.12: already separating, downward, and the clamp pulled
- * it back onto the backdrop. Measured on the default material at presence 0.08: exactly 0.0000 at
- * backdrops of 0.12, 0.20 and 0.35.
+ * The lens does not paint a body, it transforms what it refracts, in a chain that stays affine in
+ * the backdrop: a mix toward the tint at `density`, the matte lift, the medium's pull toward its
+ * own lightness, the ambient spill and the concentration of light (§3, `MEDIUM`). Composing it
+ * gives `out = A * backdrop + B` per channel, and a layer of colour `B / (1 - A)` at opacity
+ * `1 - A` over the backdrop is that, except where the colour clamps to 0..1: over a saturated dark
+ * backdrop (dark blue) a channel is off by up to 0.024.
  *
- * What the demand is DIVIDED by is deliberately the distance to the tint's pole rather than to the
- * body's own tint. Dividing by the latter is arithmetically tighter and asks for far more density
- * wherever the two are close — enough to drive it to the ceiling over a dark backdrop and stop the
- * glass being a window at all, which check:optics says plainly. Presence is a floor on visibility,
- * not a licence to go opaque.
+ * This is what lifts the body over a dark backdrop. The tint alone, under light ink, is darker
+ * than the dark it sits on; the medium's pull, the matte lift and the concentration are what make
+ * it read lighter, as in the reference (M 2:29, A 2:17).
+ *
+ * `appear` multiplies the layers exactly where the lens's `u_appear` does, so `optics` is the
+ * element's optics BEFORE `applyAppear`: scaling both would count it twice.
  */
-export function withPresence(body: GlassBody, optics: VireGlassOptics, sample: BodyBackdrop): GlassBody {
-  if (optics.presence <= 0) return body;
-  const mean = clamp(sample.luma, 0, 1);
-  // Whichever side the body is already on; with nothing to go on, the side with more room.
-  const above = Math.abs(body.tintLuma - mean) > 1e-4 ? body.tintLuma > mean : mean < 0.5;
-  const pole = above ? TINT_LIGHT : TINT_DARK;
-  const separation = Math.min(optics.presence, Math.abs(pole - mean));
-  const reached = Math.abs(body.tintLuma - mean) * body.density;
-  if (reached >= separation) return body;
-  const needed = separation / Math.max(Math.abs(pole - mean), 1e-4);
-  return {
-    density: Math.max(body.density, Math.min(needed, BODY.presenceDemand)),
-    // Left where the tint law put it, unless it landed exactly on the backdrop — which is the
-    // case that used to be created here rather than avoided.
-    tintLuma: Math.abs(body.tintLuma - mean) > 1e-4 ? body.tintLuma : pole,
+export function bodyLayer(
+  optics: VireGlassOptics,
+  sample: BodyBackdrop,
+  ink: number,
+  ambient: readonly [number, number, number],
+  appear = 1,
+): BodyLayer {
+  const a = clamp(appear, 0, 1);
+  const body = withPresence(resolveBody(optics, sample, ink), optics, sample);
+  const hue = hueOf(ambient);
+  const pickup = clamp(optics.colorPickup, 0, 1);
+  const density = clamp(body.density * a, 0, 1);
+  const matte = optics.legibility * MEDIUM.matteLift * a;
+  const pull = MEDIUM.pull * a;
+  const spill = optics.edgeLight * MEDIUM.ambientSpill * a;
+  const lift = MEDIUM.concentrate * a;
+
+  const alpha = 1 - (1 - lift) * (1 - pull) * (1 - density);
+  const channel = (i: 0 | 1 | 2): number => {
+    const tintHue = mix(1, hue[i], pickup);
+    const added =
+      (1 - pull) * (density * tintHue * body.tintLuma + matte * tintHue) +
+      pull * hue[i] * MEDIUM.luma +
+      ambient[i] * spill;
+    return alpha > 1e-6 ? clamp(((1 - lift) * added + lift) / alpha, 0, 1) : 0;
   };
+  return { r: channel(0), g: channel(1), b: channel(2), alpha };
 }

package/src/dom/index.ts

@@ -20,7 +20,7 @@ import { resolveOptics, VIREGLASS_MATERIAL, type VireGlassMaterial, type VireGla
 import { probeBackdrop } from './probe';
 import { supportsSvgBackdropFilter } from './support';
 import { boxShadowCss } from './shadow';
-import { resolveBody, withPresence } from './body';
+import { bodyLayer, resolveBody, withPresence } from './body';
 import { systemAccessibility, watchAccessibility } from './preferences';
 import { applyAccessibility, contrastRimLuma, elasticAllowed, type VireGlassAccessibility } from '../accessibility';
 import { applyGlassScale, GLASS_SCALE_DEFAULT } from '../glass-scale';
@@ -30,6 +30,7 @@ import type { VireGlassAccent } from '../adapters';
 import { concentricRadius } from '../concentric';
 import { RIM_WIDTH_PX, contrastRimCss, rimGradientCss } from './rim';
 import { GLASS_ATTR, warnIfNested } from './nesting';
+import { holdProperty } from './style-hold';
 import { REST_LIGHT } from '../adapters';
 import { refractionStrength } from '../optics';
 import { DISPERSION, TOUCH } from '../law';
@@ -289,7 +290,7 @@ function rgbCss(r: number, g: number, b: number): string {
 
 /**
  * The body, from the model's own law (`./body`, ported from the lens shader §3): density is what
- * legibility and presence demand over THIS backdrop, `tintLuma` is the lightness it tints toward,
+ * legibility and presence demand over THIS backdrop, the tint is the lightness it tints toward,
  * and the hue is the surroundings' — glass has no colour of its own, only the colour of what lies
  * beneath it. A flat fill in place of a tint is what breaks the material.
  */
@@ -297,22 +298,22 @@ function bodyCss(
   optics: VireGlassOptics,
   sample: BackdropSample,
   ink: number,
-  accent?: VireGlassAccent,
+  accent: VireGlassAccent | undefined,
+  appear: number,
 ): string {
-  const body = withPresence(resolveBody(optics, sample, ink), optics, sample);
-
   // A tinted element takes its colour from the accent rather than from its surroundings, but it is
   // still the MEDIUM that is coloured: the amount stays short of one so the content keeps coming
   // through. A fill at full opacity is the thing §7 says breaks the material.
   if (accent) {
+    const settled = applyAppear(optics, appear);
+    const body = withPresence(resolveBody(settled, sample, ink), settled, sample);
     const [r, g, b] = accentTone(accent.color, sample.luma);
     const amount = Math.max(accentAmount(accent), body.density);
     return `rgba(${to255(r)}, ${to255(g)}, ${to255(b)}, ${amount.toFixed(3)})`;
   }
 
-  const [r, g, b] = ambientFrom(sample);
-  const hue = (c: number) => body.tintLuma + (c - body.tintLuma) * optics.colorPickup;
-  return `rgba(${to255(hue(r))}, ${to255(hue(g))}, ${to255(hue(b))}, ${body.density.toFixed(3)})`;
+  const layer = bodyLayer(optics, sample, ink, ambientFrom(sample), appear);
+  return `rgba(${to255(layer.r)}, ${to255(layer.g)}, ${to255(layer.b)}, ${layer.alpha.toFixed(3)})`;
 }
 
 export type AttachGlassOptions = {
@@ -354,9 +355,19 @@ export type AttachGlassOptions = {
   onGlow?: (glow: { pageX: number; pageY: number; strength: number } | null) => void;
   /** Pointer response (§5). On by default. */
   interactive?: boolean;
-  /** Overrides the probe entirely — images and video are invisible to it, and the host app
-   *  already knows its own cover-art accent. */
+  /**
+   * Overrides the probe entirely. The probe reads declared backgrounds, so images, video and
+   * canvases are invisible to it; a host that knows its backdrop (a cover's accent, a gradient)
+   * states it here, and changes it later with `setSample`. `statsFromSamples` builds one from
+   * a handful of colours.
+   */
   sample?: BackdropSample;
+  /**
+   * Whether `attachGlass` paints the body as the element's `background-color`. On by default;
+   * turn it off if the host owns that property — `--vireglass-body-color` is always emitted
+   * either way and carries the same colour.
+   */
+  body?: boolean;
 };
 
 /**
@@ -395,6 +406,11 @@ export type GlassHandle = {
   /** A glow that started on a neighbour, in page coordinates (§5). Null clears it. */
   setNeighbourGlow(glow: { pageX: number; pageY: number; strength: number } | null): void;
   setMorph(morph: GlassMorph | null): void;
+  /**
+   * Replaces the backdrop the glass adapts to, without re-attaching, and repaints. The same
+   * object as `sample` in the options; `null` goes back to probing declared backgrounds.
+   */
+  setSample(sample: BackdropSample | null): void;
   destroy(): void;
 };
 
@@ -418,6 +434,7 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
   const onlyWhenTouched = opts.variant === 'interactive';
   let appear = onlyWhenTouched ? 0 : (opts.appear ?? 1);
   let accent = opts.accent;
+  let supplied = opts.sample;
   // Read once at attach, then followed: a setting turned on while the page is open has to reach
   // the material, not wait for a reload.
   let a11y = systemAccessibility();
@@ -436,6 +453,7 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
   el.setAttribute(GLASS_ATTR, '');
   // `inset: 0` on the rim needs a positioned ancestor. Only taken over when the host left it at
   // the initial value, and put back on destroy.
+  const restoreBackground = holdProperty(el.style, 'background-color');
   const positionWasStatic = getComputedStyle(el).position === 'static';
   if (positionWasStatic) el.style.setProperty('position', 'relative');
 
@@ -445,13 +463,16 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
    * edge of the scale under increased contrast, because the user needs contrast more than they
    * need the aesthetic.
    */
-  function optics(patch?: Partial<VireGlassMaterial>): VireGlassOptics {
+  function settledOptics(patch?: Partial<VireGlassMaterial>): VireGlassOptics {
     const base = resolveOptics(patch ?? opts.material);
     const scaled = applyGlassScale(base, opts.scale ?? GLASS_SCALE_DEFAULT);
-    const settled = applyAccessibility(scaled, opts.accessibility ?? a11y);
+    return applyAccessibility(scaled, opts.accessibility ?? a11y);
+  }
+
+  function optics(patch?: Partial<VireGlassMaterial>): VireGlassOptics {
     // Appearance last, and by modulating the lens rather than by fading the element: §1 is
     // explicit that opacity is the wrong instrument for this.
-    return applyAppear(settled, appear);
+    return applyAppear(settledOptics(patch), appear);
   }
 
   function morphState() {
@@ -470,7 +491,10 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
     if (destroyed) return;
     const geometry = opts.geometry ?? measureGeometry(el);
     const opticsNow = optics();
-    const sample = opts.sample ?? probeBackdrop(el);
+    const sample = supplied ?? probeBackdrop(el);
+    const light = shouldInkBeLight(sample, wasLight);
+    wasLight = light;
+    const body = opts.body === false ? null : bodyCss(settledOptics(), sample, light ? 1 : 0, accent, appear);
 
     if (svgSupported) {
       // The map depends only on geometry, optics and density — never on the backdrop. Rebuilding
@@ -495,11 +519,9 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
     } else {
       el.style.setProperty('backdrop-filter', fallbackFilterCss(opticsNow));
       el.style.setProperty('-webkit-backdrop-filter', fallbackFilterCss(opticsNow));
-      el.style.backgroundColor = bodyCss(opticsNow, sample, wasLight ? 1 : 0, accent);
     }
+    if (body) el.style.backgroundColor = body;
 
-    const light = shouldInkBeLight(sample, wasLight);
-    wasLight = light;
     const [tr, tg, tb] = ambientFrom(sample);
     el.style.setProperty('--vireglass-ink', light ? '1' : '0');
     el.style.setProperty('--vireglass-tint', `${tr} ${tg} ${tb}`);
@@ -511,7 +533,10 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
     const inkLevel = Math.round((light ? INK_LIGHT : INK_DARK) * 255);
     el.style.setProperty('--vireglass-ink-color', `rgb(${inkLevel} ${inkLevel} ${inkLevel})`);
     el.style.setProperty('--vireglass-tint-color', rgbCss(tr, tg, tb));
-    el.style.setProperty('--vireglass-body-color', bodyCss(opticsNow, sample, light ? 1 : 0, accent));
+    el.style.setProperty(
+      '--vireglass-body-color',
+      body ?? bodyCss(settledOptics(), sample, light ? 1 : 0, accent, appear),
+    );
 
     // Rim and shadow follow the SAMPLE, not just the geometry, so they sit outside the map's
     // cache key: the environment they take their colour and density from moves under a scroll
@@ -616,7 +641,7 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
       el.style.setProperty('--vireglass-glow-opacity', '0');
       return;
     }
-    const [gr, gg, gb] = ambientFrom(opts.sample ?? probeBackdrop(el));
+    const [gr, gg, gb] = ambientFrom(supplied ?? probeBackdrop(el));
     const cx = ((x + geometry.width / 2) / geometry.width) * 100;
     const cy = ((y + geometry.height / 2) / geometry.height) * 100;
     const reach = halfMinDp(geometry) * TOUCH_RADIUS_FRACTION;
@@ -725,7 +750,7 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
     mapKey = '';
     el.style.removeProperty('backdrop-filter');
     el.style.removeProperty('-webkit-backdrop-filter');
-    el.style.removeProperty('background-color');
+    if (opts.body !== false) restoreBackground();
     el.style.removeProperty('--vireglass-ink');
     el.style.removeProperty('--vireglass-tint');
     el.style.removeProperty('--vireglass-body-density');
@@ -774,6 +799,10 @@ export function attachGlass(el: HTMLElement, opts: AttachGlassOptions = {}): Gla
       mapKey = '';
       apply();
     },
+    setSample(next) {
+      supplied = next ?? undefined;
+      apply();
+    },
     destroy,
   };
   attached.set(el, handle);

package/src/dom/probe.ts

@@ -40,7 +40,7 @@ function luma(r: number, g: number, b: number): number {
  * formula here would mean the ink-polarity decision quietly drifts between renderers on the same
  * page. `samples` are 0..255 per channel, matching what `parseColor` returns.
  */
-export function statsFromSamples(samples: readonly RgbColor[]): BackdropSample {
+export function statsFromSamples(samples: readonly (Omit<RgbColor, 'a'> & { a?: number })[]): BackdropSample {
   const n = samples.length;
   if (n === 0) return { luma: 0.5, busy: 0, lo: 0.5, hi: 0.5, r: 0.5, g: 0.5, b: 0.5 };
 

package/src/dom/rim.ts

@@ -1,15 +1,20 @@
-// Rim light (docs/reference.md §2): a hairline along the silhouette — "not a band and not a
-// bevel" — carrying two opposing arcs, the rest of it outlined by a thin dark line, and its colour
-// taken from the environment.
+// Rim light (docs/reference.md §2): a hairline along the whole silhouette — "not a band and not a
+// bevel" — brighter toward the key light, with a second, weaker arc opposite it, outlined by a thin
+// dark line, its colour taken from the environment and its strength from how light that is.
 //
-// Every number here is the lens shader's own. The key-light lobe is `lens-shader.ts` line 375
-// verbatim (exponent 3, opposing arc at 0.45), and the dark edge is its line 528 (a 0.22
-// darkening at the silhouette). The only thing that differs is the primitive: a conic gradient
-// sampled at fixed angles instead of a per-pixel normal.
+// Every number here is the lens shader's own, read from the law. The only thing that differs is
+// the primitive: a conic gradient sampled at fixed angles instead of a per-pixel normal.
 import { RIM } from '../law';
 import type { VireGlassOptics } from '../material';
 
-const { lobeExponent: LOBE_EXPONENT, opposingArc: OPPOSING_ARC, darkEdge: DARK_EDGE } = RIM;
+const {
+  lobeExponent: LOBE_EXPONENT,
+  opposingArc: OPPOSING_ARC,
+  darkEdge: DARK_EDGE,
+  contour: CONTOUR,
+  whiteShare: WHITE_SHARE,
+  reflectanceRef: REFLECTANCE_REF,
+} = RIM;
 
 /** One stop every 7.5°. Fine enough that a cubic lobe reads as a smooth arc rather than a fan. */
 const STOPS = 48;
@@ -39,13 +44,45 @@ const to255 = (v: number) => Math.round(clamp01(v) * 255);
 
 export type RimAmbient = readonly [number, number, number];
 
+const mixTo = (a: number, b: number, t: number) => a + (b - a) * t;
+
+function smoothstep(edge0: number, edge1: number, x: number): number {
+  const t = clamp01((x - edge0) / (edge1 - edge0));
+  return t * t * (3 - 2 * t);
+}
+
+/** Lightness of an ambient colour, the weights the lens uses. */
+export function ambientLuma(ambient: RimAmbient): number {
+  return 0.2126 * ambient[0] + 0.7152 * ambient[1] + 0.0722 * ambient[2];
+}
+
+/** How strongly the line is drawn over a surround of this lightness (§2, §6). */
+export function rimStrength(luma: number): number {
+  return mixTo(RIM.strengthDark, RIM.strengthLight, smoothstep(RIM.ambientFrom, RIM.ambientTo, luma));
+}
+
 /**
- * The gradient for the hairline. Colour comes from the environment — "over a yellow flower the rim
- * is yellow, over sky it is blue" (§2) — lifted toward white where the key light lands. Away from
- * both arcs only the dark edge remains.
+ * The line's opacity where the rim's normal sits `deltaDeg` from the light: a floor all the way
+ * round and the key-light lobe on top of it, all of it scaled by the medium's reflectance up to
+ * the reference material's.
+ */
+export function rimLineAlpha(deltaDeg: number, optics: VireGlassOptics, luma: number): number {
+  const reflect = Math.min(optics.fresnel / REFLECTANCE_REF, 1);
+  const damping = optics.fresnel > 0 ? optics.specular / optics.fresnel : 0;
+  const lobe = rimLobe(deltaDeg, damping);
+  return clamp01(rimStrength(luma) * reflect * (CONTOUR + (1 - CONTOUR) * lobe));
+}
+
+/**
+ * The gradient for the hairline: a light line round the whole contour, brighter toward the key
+ * light, drawn over the dark edge. Its colour comes from the environment — "over a yellow flower
+ * the rim is yellow, over sky it is blue" (§2) — lifted toward white, and its strength follows how
+ * light the environment is.
  *
  * The opposing arc carries an iridescent fringe (§2), so `iridescence` pulls its channels apart
  * rather than lifting them together.
+ *
+ * Two layers, the line first: `--vireglass-rim` is a background list and paints as one.
  */
 export function rimGradientCss(
   optics: VireGlassOptics,
@@ -56,31 +93,29 @@ export function rimGradientCss(
   const present = clamp01(appear);
   const start = lightConicAngle(light);
   const [ar, ag, ab] = ambient;
-  const stops: string[] = [];
+  const luma = ambientLuma(ambient);
+  const line: string[] = [];
 
   for (let i = 0; i <= STOPS; i += 1) {
     const angle = (i / STOPS) * 360;
-    const key = rimLobe(angle, optics.specular);
     const facing = Math.cos((angle * Math.PI) / 180);
     // The far arc is where dispersion shows as a fringe; the near one is a clean specular.
     const fringe = facing < 0 ? optics.iridescence * OPPOSING_ARC : 0;
-    const lift = clamp01(key * optics.fresnel);
-
-    const r = ar + (1 - ar) * clamp01(lift + fringe);
-    const g = ag + (1 - ag) * lift;
-    const b = ab + (1 - ab) * clamp01(lift - fringe);
-
-    // Scaled, not floored: the dark edge is the one part of the rim that survives facing away from
-    // the light, so leaving it unscaled leaves a hairline drawn around an element that is not there.
-    const alpha = clamp01(DARK_EDGE + lift * (1 - DARK_EDGE)) * present;
-    // Below the arcs the line is the dark edge itself, not a dim copy of the environment.
-    const colour = lift > 0.001
-      ? `rgba(${to255(r)},${to255(g)},${to255(b)},${alpha.toFixed(3)})`
-      : `rgba(0,0,0,${alpha.toFixed(3)})`;
-    stops.push(`${colour} ${angle.toFixed(1)}deg`);
+
+    const r = ar + (1 - ar) * clamp01(WHITE_SHARE + fringe);
+    const g = ag + (1 - ag) * WHITE_SHARE;
+    const b = ab + (1 - ab) * clamp01(WHITE_SHARE - fringe);
+    const alpha = rimLineAlpha(angle, optics, luma) * present;
+    line.push(`rgba(${to255(r)},${to255(g)},${to255(b)},${alpha.toFixed(3)}) ${angle.toFixed(1)}deg`);
   }
 
-  return `conic-gradient(from ${start.toFixed(1)}deg, ${stops.join(', ')})`;
+  // Scaled by presence, not floored: the dark edge would otherwise outline an element that is not
+  // there yet.
+  const dark = `rgba(0,0,0,${(DARK_EDGE * present).toFixed(3)})`;
+  return (
+    `conic-gradient(from ${start.toFixed(1)}deg, ${line.join(', ')}), ` +
+    `conic-gradient(${dark} 0deg, ${dark} 360deg)`
+  );
 }
 
 export const RIM_WIDTH_PX = RIM.widthPx;