vireglass 2.3.1 → 3.0.1

package/dist/dom.d.cts

@@ -1,8 +1,8 @@
 import { B as BackdropSample } from './adaptation-BSbbdExK.cjs';
-import { V as VireGlassGeometry } from './geometry-RhKd7CM5.cjs';
-import { V as VireGlassOptics, a as VireGlassMaterial } from './material-CnUmdKg1.cjs';
-import { T as TouchWarp, M as MorphShape, V as VireGlassAccessibility, S as ScrollEdgeStyle, G as GroupPlane } from './group-model-DwtixGhG.cjs';
-import { V as VireGlassAccent } from './adapters-BOPIRMnL.cjs';
+import { V as VireGlassGeometry } from './geometry-ip9WSlZv.cjs';
+import { V as VireGlassOptics, a as VireGlassMaterial } from './material-D9m1EN47.cjs';
+import { T as TouchWarp, M as MorphShape, V as VireGlassAccessibility, S as ScrollEdgeStyle, G as GroupPlane } from './group-model-DX2_W9J_.cjs';
+import { V as VireGlassAccent } from './adapters--bXcGvhW.cjs';
 
 /** Any `backdrop-filter` at all (e.g. `blur()`) — the fallback path's own requirement. */
 declare function supportsBackdropFilter(): boolean;
@@ -32,7 +32,9 @@ declare function parseColor(value: string): RgbColor | null;
  * 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.
  */
-declare function statsFromSamples(samples: readonly RgbColor[]): BackdropSample;
+declare function statsFromSamples(samples: readonly (Omit<RgbColor, 'a'> & {
+    a?: number;
+})[]): BackdropSample;
 /**
  * Composites a stack of backgrounds front to back, the way the compositor does.
  *
@@ -100,13 +102,26 @@ declare function lightConicAngle(light: readonly [number, number]): number;
  *  the light. Both arcs come out of this one expression — that is why they are opposed. */
 declare function rimLobe(deltaDeg: number, specular: number): number;
 type RimAmbient = readonly [number, number, number];
+/** Lightness of an ambient colour, the weights the lens uses. */
+declare function ambientLuma(ambient: RimAmbient): number;
+/** How strongly the line is drawn over a surround of this lightness (§2, §6). */
+declare function rimStrength(luma: number): number;
 /**
- * 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.
+ */
+declare function rimLineAlpha(deltaDeg: number, optics: VireGlassOptics, luma: number): number;
+/**
+ * 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.
  */
 declare function rimGradientCss(optics: VireGlassOptics, ambient: RimAmbient, light: readonly [number, number], appear?: number): string;
 declare const RIM_WIDTH_PX: 1;
@@ -119,7 +134,7 @@ declare const RIM_WIDTH_PX: 1;
  * everything around it. It has to hold at every angle, including the one facing away from the key
  * light where the ordinary rim falls back to a dim dark line.
  */
-declare function contrastRimCss(bodyLuma: number, rimLuma: number): string;
+declare function contrastRimCss(bodyLuma: number, rimLuma: number, appear?: number): string;
 
 declare function shadowAlphaFrom(sample: {
     busy: number;
@@ -151,6 +166,9 @@ 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;
 };
 /**
  * `ink` is POLARITY, 1 light and 0 dark, matching the shader's uniform. The requirements are
@@ -160,23 +178,37 @@ type GlassBody = {
 declare function resolveBody(optics: VireGlassOptics, sample: BodyBackdrop, ink: number): GlassBody;
 /**
  * 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.
+ */
+declare function withPresence(body: GlassBody, optics: VireGlassOptics, _sample?: BodyBackdrop): GlassBody;
+type BodyLayer = {
+    /** Straight (not premultiplied) colour, 0…1 per channel. */
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+};
+/**
+ * The body as ONE translucent layer over the backdrop, which is the form the DOM can draw it in.
+ *
+ * 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.
  *
- * 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.
+ * 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).
  *
- * 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.
+ * `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.
  */
-declare function withPresence(body: GlassBody, optics: VireGlassOptics, sample: BodyBackdrop): GlassBody;
+declare function bodyLayer(optics: VireGlassOptics, sample: BodyBackdrop, ink: number, ambient: readonly [number, number, number], appear?: number): BodyLayer;
 
 declare function systemAccessibility(): VireGlassAccessibility;
 /** Fires whenever any of the three changes. The material has to follow a setting turned on while
@@ -320,9 +352,19 @@ type AttachGlassOptions = {
     } | 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;
 };
 /**
  * Shapes this element flows into (docs/reference.md §5): merging with a neighbour, or splitting
@@ -363,8 +405,13 @@ type GlassHandle = {
         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;
 };
 declare function attachGlass(el: HTMLElement, opts?: AttachGlassOptions): GlassHandle;
 
-export { type AttachGlassOptions, type BodyBackdrop, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, attachGlass, attachScrollEdge, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, resetSupportCache, resolveBody, rimGradientCss, rimLobe, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };
+export { type AttachGlassOptions, type BodyBackdrop, type BodyLayer, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };

package/dist/dom.d.ts

@@ -1,8 +1,8 @@
 import { B as BackdropSample } from './adaptation-BSbbdExK.js';
-import { V as VireGlassGeometry } from './geometry-GvXtt-_S.js';
-import { V as VireGlassOptics, a as VireGlassMaterial } from './material-CnUmdKg1.js';
-import { T as TouchWarp, M as MorphShape, V as VireGlassAccessibility, S as ScrollEdgeStyle, G as GroupPlane } from './group-model-z4N27qsC.js';
-import { V as VireGlassAccent } from './adapters-B_amRBqc.js';
+import { V as VireGlassGeometry } from './geometry-pabkYV7w.js';
+import { V as VireGlassOptics, a as VireGlassMaterial } from './material-D9m1EN47.js';
+import { T as TouchWarp, M as MorphShape, V as VireGlassAccessibility, S as ScrollEdgeStyle, G as GroupPlane } from './group-model-CQiI5cCe.js';
+import { V as VireGlassAccent } from './adapters-BlMhc6pI.js';
 
 /** Any `backdrop-filter` at all (e.g. `blur()`) — the fallback path's own requirement. */
 declare function supportsBackdropFilter(): boolean;
@@ -32,7 +32,9 @@ declare function parseColor(value: string): RgbColor | null;
  * 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.
  */
-declare function statsFromSamples(samples: readonly RgbColor[]): BackdropSample;
+declare function statsFromSamples(samples: readonly (Omit<RgbColor, 'a'> & {
+    a?: number;
+})[]): BackdropSample;
 /**
  * Composites a stack of backgrounds front to back, the way the compositor does.
  *
@@ -100,13 +102,26 @@ declare function lightConicAngle(light: readonly [number, number]): number;
  *  the light. Both arcs come out of this one expression — that is why they are opposed. */
 declare function rimLobe(deltaDeg: number, specular: number): number;
 type RimAmbient = readonly [number, number, number];
+/** Lightness of an ambient colour, the weights the lens uses. */
+declare function ambientLuma(ambient: RimAmbient): number;
+/** How strongly the line is drawn over a surround of this lightness (§2, §6). */
+declare function rimStrength(luma: number): number;
 /**
- * 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.
+ */
+declare function rimLineAlpha(deltaDeg: number, optics: VireGlassOptics, luma: number): number;
+/**
+ * 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.
  */
 declare function rimGradientCss(optics: VireGlassOptics, ambient: RimAmbient, light: readonly [number, number], appear?: number): string;
 declare const RIM_WIDTH_PX: 1;
@@ -119,7 +134,7 @@ declare const RIM_WIDTH_PX: 1;
  * everything around it. It has to hold at every angle, including the one facing away from the key
  * light where the ordinary rim falls back to a dim dark line.
  */
-declare function contrastRimCss(bodyLuma: number, rimLuma: number): string;
+declare function contrastRimCss(bodyLuma: number, rimLuma: number, appear?: number): string;
 
 declare function shadowAlphaFrom(sample: {
     busy: number;
@@ -151,6 +166,9 @@ 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;
 };
 /**
  * `ink` is POLARITY, 1 light and 0 dark, matching the shader's uniform. The requirements are
@@ -160,23 +178,37 @@ type GlassBody = {
 declare function resolveBody(optics: VireGlassOptics, sample: BodyBackdrop, ink: number): GlassBody;
 /**
  * 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.
+ */
+declare function withPresence(body: GlassBody, optics: VireGlassOptics, _sample?: BodyBackdrop): GlassBody;
+type BodyLayer = {
+    /** Straight (not premultiplied) colour, 0…1 per channel. */
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+};
+/**
+ * The body as ONE translucent layer over the backdrop, which is the form the DOM can draw it in.
+ *
+ * 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.
  *
- * 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.
+ * 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).
  *
- * 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.
+ * `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.
  */
-declare function withPresence(body: GlassBody, optics: VireGlassOptics, sample: BodyBackdrop): GlassBody;
+declare function bodyLayer(optics: VireGlassOptics, sample: BodyBackdrop, ink: number, ambient: readonly [number, number, number], appear?: number): BodyLayer;
 
 declare function systemAccessibility(): VireGlassAccessibility;
 /** Fires whenever any of the three changes. The material has to follow a setting turned on while
@@ -320,9 +352,19 @@ type AttachGlassOptions = {
     } | 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;
 };
 /**
  * Shapes this element flows into (docs/reference.md §5): merging with a neighbour, or splitting
@@ -363,8 +405,13 @@ type GlassHandle = {
         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;
 };
 declare function attachGlass(el: HTMLElement, opts?: AttachGlassOptions): GlassHandle;
 
-export { type AttachGlassOptions, type BodyBackdrop, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, attachGlass, attachScrollEdge, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, resetSupportCache, resolveBody, rimGradientCss, rimLobe, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };
+export { type AttachGlassOptions, type BodyBackdrop, type BodyLayer, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };