vireglass 0.1.0

package/src/adapters.ts

@@ -0,0 +1,362 @@
+import {
+  bevelDp,
+  bevelFraction,
+  halfMinDp,
+  rimDp,
+  shadowReachDp,
+  surfacePadDp,
+  thicknessDp,
+  type VireGlassGeometry,
+} from './geometry';
+import { LENS_SHADER } from './lens-shader';
+import { debugIndex, type VireGlassDebugMode, type VireGlassOptics } from './material';
+
+/** Smooth union with a second shape — bench morphing experiment only. */
+export 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. */
+export type VireGlassTouch = {
+  x: number;
+  y: number;
+  pullX: number;
+  pullY: number;
+  press: number;
+  radius: number;
+  waveAmp: number;
+  wavePhase: number;
+};
+
+const NO_TOUCH: VireGlassTouch = {
+  x: 0, y: 0, pullX: 0, pullY: 0, press: 0, radius: 0, waveAmp: 0, wavePhase: 0,
+};
+
+const NO_MORPH = { offsetX: 0, offsetY: 0, width: 0, height: 0, cornerRadius: 0, smoothing: 0 };
+
+/** No progress. Negative rather than zero: zero is the start of the track, a legitimate value. */
+const NO_PROGRESS = -1;
+
+/** Tinted glass for the primary action (M 16:08). Color is RGB 0…1. */
+export type VireGlassAccent = { color: readonly [number, number, number]; amount?: number };
+
+/** Default tint fraction: the color reads, but content beneath it is still visible. */
+export const ACCENT_AMOUNT = 0.8;
+const NO_ACCENT = [0, 0, 0, 0] as const;
+
+
+
+/** 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. */
+export const lensMagnify = (o: VireGlassOptics) => 1 + (o.refractionScale - 1) * o.refraction;
+
+/**
+ * Lens uniforms. Assembled as ONE channel: name, size and values travel together, so a mismatch
+ * with the shader is caught immediately, with the name right there in the log. There used to be a
+ * separate Kotlin `Prop` per value — Expo swallows an unknown prop silently, and the lens simply
+ * never turned on (docs/material-lab.md E-01, which is how refraction ended up disabled for an
+ * entire phase).
+ *
+ * Everything with a dimension is converted to PIXELS right here. The native view is left with
+ * only the uniforms it alone knows: its own size and its own place on screen.
+ */
+// The lens's uniform names and sizes are always the same — the set is fixed. They're handed over
+// as ONE instance for the whole process: otherwise every frame of a drag would send three dozen
+// fresh strings to the native side, React can't tell "unchanged" from "a new array", and motion
+// goes stepwise. The values are the only thing that actually changes.
+const shapes = new Map<number, { names: string[]; sizes: number[] }>();
+
+function channel(entries: [string, number | readonly number[]][]) {
+  const uniformValues: number[] = [];
+  let shape = shapes.get(entries.length);
+  let same = shape !== undefined;
+  for (let i = 0; i < entries.length; i += 1) {
+    const [name, value] = entries[i];
+    const v = typeof value === 'number' ? [value] : value;
+    if (same && (shape!.names[i] !== name || shape!.sizes[i] !== v.length)) same = false;
+    for (const x of v) uniformValues.push(x);
+  }
+  if (!same) {
+    shape = {
+      names: entries.map((e) => e[0]),
+      sizes: entries.map((e) => (typeof e[1] === 'number' ? 1 : e[1].length)),
+    };
+    shapes.set(entries.length, shape);
+  }
+  return { uniformNames: shape!.names, uniformSizes: shape!.sizes, uniformValues };
+}
+
+/** 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). */
+export 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;
+  } = {},
+) {
+  const morph = options.morph ?? NO_MORPH;
+  const morph2 = options.morph2 ?? NO_MORPH;
+  const touch = options.touch ?? NO_TOUCH;
+  // Backdrop estimate for the whole surface group. Travels through the same channel as the
+  // material and applies AFTER the lens's own estimate — that is, it simply overrides it. It
+  // can't travel as a separate prop: the lens view is wrapped in an animated component.
+  const g = options.groupProbe;
+  const group: [string, number | readonly number[]][] =
+    g && g.length >= 9
+      ? [
+          ['u_probeLuma', g[0]],
+          ['u_probeBusy', g[1]],
+          ['u_probeRange', [g[2], g[3]]],
+          ['u_probeSlope', [g[4], g[5]]],
+          ['u_probe', [g[6], g[7], g[8]]],
+        ]
+      : [];
+  const d = density;
+  const halfW = (geometry.width * d) / 2;
+  const halfH = (geometry.height * d) / 2;
+  const halfMin = Math.min(halfW, halfH);
+
+  return {
+    shaderSource: LENS_SHADER,
+    glassWidth: geometry.width,
+    glassHeight: geometry.height,
+    ...channel([
+      ['u_halfSize', [halfW, halfH]],
+      ['u_corner', Math.min(geometry.cornerRadius * d, halfMin)],
+      ['u_bevel', Math.max(bevelDp(geometry, optics) * d, 1)],
+      ['u_thick', thicknessDp(geometry, optics) * d],
+      ['u_rim', rimDp(geometry, optics) * d],
+      ['u_ior', optics.ior],
+      ['u_iorSpread', optics.iorSpread],
+      ['u_light', options.light ?? REST_LIGHT],
+      ['u_appear', options.appear ?? 1],
+      ['u_accent', options.accent ? [...options.accent.color, options.accent.amount ?? ACCENT_AMOUNT] : NO_ACCENT],
+      // Haze from surface roughness. Lives in the same disc-gather pass as adaptive scattering,
+      // and fades out toward the bevel: that's a different job there — bending the ray and
+      // splitting it.
+      ['u_frost', optics.blur * d],
+      ['u_ink', optics.ink],
+      ['u_legibility', optics.legibility],
+      ['u_dim', optics.dimming],
+      ['u_presence', optics.presence],
+      ['u_adaptRadius', optics.adaptRadius * d],
+      ['u_bodyDensity', optics.bodyDensity],
+      ['u_edgeLight', optics.edgeLight],
+      ['u_fresnel', optics.fresnel],
+      ['u_specular', optics.specular],
+      // The rim gathers light from the element's vicinity — this is a radius around the shape,
+      // not its bevel.
+      ['u_reflectReach', optics.gatherRadiusDp * d],
+      ['u_film', optics.film],
+      ['u_iridescence', optics.iridescence],
+      ['u_diffraction', optics.diffraction],
+      ['u_colorPickup', optics.colorPickup],
+      ['u_morphOffset', [morph.offsetX * d, morph.offsetY * d]],
+      ['u_morphHalf', [(morph.width * d) / 2, (morph.height * d) / 2]],
+      ['u_morphCorner', morph.cornerRadius * d],
+      ['u_morphK', morph.smoothing * d],
+      ['u_morph2Offset', [morph2.offsetX * d, morph2.offsetY * d]],
+      ['u_morph2Half', [(morph2.width * d) / 2, (morph2.height * d) / 2]],
+      ['u_morph2Corner', morph2.cornerRadius * d],
+      ['u_touch', [touch.x * d, touch.y * d]],
+      ['u_pull', [touch.pullX * d, touch.pullY * d]],
+      ['u_touchPress', touch.press],
+      ['u_touchRadius', touch.radius * d],
+      ['u_wave', [touch.waveAmp * d, touch.wavePhase]],
+      ['u_progress', options.progress ?? NO_PROGRESS],
+      ['u_debug', debugIndex(options.debug ?? 'normal')],
+      ...group,
+    ]),
+  };
+}
+
+/** 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. */
+export 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;
+  } = {},
+) {
+  const morph = options.morph ?? NO_MORPH;
+  const morph2 = options.morph2 ?? NO_MORPH;
+  const touch = options.touch ?? NO_TOUCH;
+  const pad = surfacePadDp(geometry, options.dragLimit ?? 0, morph);
+  return {
+    u_center: [geometry.width / 2 + pad, geometry.height / 2 + pad],
+    u_halfSize: [geometry.width / 2, geometry.height / 2],
+    u_corner: Math.min(geometry.cornerRadius, halfMinDp(geometry)),
+    u_bevel: bevelDp(geometry, optics),
+    u_thickness: bevelFraction(geometry, optics),
+    u_morphOffset: [morph.offsetX, morph.offsetY],
+    u_morphHalf: [morph.width / 2, morph.height / 2],
+    u_morphCorner: morph.cornerRadius,
+    u_morphK: morph.smoothing,
+    u_morph2Offset: [morph2.offsetX, morph2.offsetY],
+    u_morph2Half: [morph2.width / 2, morph2.height / 2],
+    u_morph2Corner: morph2.cornerRadius,
+    u_edgeDensity: optics.edgeDensity,
+    u_dispersion: optics.dispersion,
+    u_refraction: optics.refraction,
+    // Tint density is suppressed when the lens is drawing the body: painting it twice would
+    // double the fill, and adaptation is impossible on the surface anyway — it can't see the
+    // backdrop. The color itself stays: it drives absorption at the rim.
+    u_tint: [
+      optics.tint.r,
+      optics.tint.g,
+      optics.tint.b,
+      options.bodyInLens ? 0 : optics.tintStrength,
+    ],
+    u_shadow: options.shadow ?? 1,
+    // Neutral by default: without an ambient sample, the shadow stays exactly as it was.
+    u_ambient: options.ambient ?? [0, 0, 0],
+    u_shadowReach: shadowReachDp(geometry),
+    u_touch: [touch.x, touch.y],
+    u_pull: [touch.pullX, touch.pullY],
+    u_touchPress: touch.press,
+    u_touchRadius: touch.radius,
+    u_wave: [touch.waveAmp, touch.wavePhase],
+    u_presence: optics.presence,
+    u_progress: options.progress ?? NO_PROGRESS,
+    u_appear: options.appear ?? 1,
+    // Zero by default: buttons sink in, the way every element behaved before this rule existed.
+    u_lift: options.lift ?? 0,
+
+    u_debug: debugIndex(options.debug ?? 'normal'),
+  };
+}
+
+/**
+ * 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.
+ */
+export type SurfaceUniforms = ReturnType<typeof toSurfaceUniforms>;
+
+export const SURFACE_LENGTH_UNIFORMS = [
+  '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',
+  // `satisfies`, not just `as const`: otherwise a typo in the name compiles silently and makes it
+  // to runtime — the field with the garbage name gets NaN, and the real one is left un-multiplied.
+] as const satisfies readonly (keyof SurfaceUniforms)[];
+
+/**
+ * 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.
+ */
+export function toDeviceSurfaceUniforms(raw: SurfaceUniforms, density: number): SurfaceUniforms {
+  const scaled: Record<string, unknown> = { ...raw };
+  for (const key of SURFACE_LENGTH_UNIFORMS) {
+    const value: unknown = scaled[key];
+    scaled[key] = Array.isArray(value)
+      ? (value as number[]).map((v) => v * density)
+      : (value as number) * density;
+  }
+  // Of the wave, only the amplitude has a length; the phase is in turns and knows nothing about density.
+  scaled.u_wave = [raw.u_wave[0] * density, raw.u_wave[1]];
+  return scaled as SurfaceUniforms;
+}
+
+/** Key light direction in screen coordinates, for when the orientation response is off. */
+export const REST_LIGHT: readonly [number, number] = [-0.577, -0.817];
+
+/** 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). */
+export const DYNAMIC_UNIFORMS = ['u_press', 'u_active'] as const;
+
+export const ICON_UNIFORMS = ['u_iconOn', 'u_iconScale', 'u_inkIdle', 'u_inkActive'] as const;
+
+/** 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. */
+export const OVERLAY_UNIFORMS = ['u_overlayOn'] as const;
+
+/**
+ * Fusing two surfaces into one continuous medium.
+ *
+ * The second shape is described RELATIVE to the first one's center, because both live in the
+ * same shader: the union has no "two pieces of glass," just one body with two bulges — the mask,
+ * the refraction and the rim are all computed from a single shared scene.
+ *
+ * `t` — how fused the shapes are: 0 turns the second shape off before any computation, 1 gives a
+ * single shared medium. The seam's smoothing radius is a fraction of the smaller half-size: on
+ * large elements the bridge has to be wider, otherwise the seam is left with a sharp corner,
+ * which doesn't happen in a liquid.
+ */
+const MORPH_NECK = 0.35;
+
+export function morphBetween(
+  a: VireGlassGeometry,
+  b: VireGlassGeometry,
+  offsetX: number,
+  offsetY: number,
+  t: number,
+): VireGlassMorph | undefined {
+  if (t <= 0) return undefined;
+  const half = Math.min(halfMinDp(a), halfMinDp(b));
+  return {
+    offsetX,
+    offsetY,
+    width: b.width,
+    height: b.height,
+    cornerRadius: b.cornerRadius,
+    smoothing: half * MORPH_NECK * Math.min(t, 1),
+  };
+}

package/src/concentric.ts

@@ -0,0 +1,25 @@
+// Concentricity (reference 219 @7:53): nested shapes share the CENTER of curvature, not the radius.
+// So the inner shape's radius is smaller by exactly the inset — otherwise the corners don't run
+// parallel and the gap between the shapes either gets eaten or spreads apart.
+
+/**
+ * Radius of a nested shape: outer radius minus inset. Zero is a square corner; it never goes
+ * negative — once the inset exceeds the outer radius, the corner is simply a right angle.
+ *
+ * `minimum` — a floor on the radius (analogous to `concentric(minimum:)` in SwiftUI): far from
+ * the edge, honest concentricity yields zero and the nested element drops out of the family with
+ * a sharp corner. The floor breaks concentricity on purpose — here kinship between shapes matters
+ * more than a shared center of curvature.
+ */
+export function concentricRadius(outerRadius: number, inset: number, minimum = 0): number {
+  return Math.max(outerRadius - inset, Math.max(minimum, 0));
+}
+
+/**
+ * The inset at which an inner shape with a given radius stays concentric with the outer one.
+ * The inverse problem: the element's radius is known (its size dictates it), and what's needed
+ * is the margin around it.
+ */
+export function concentricInset(outerRadius: number, innerRadius: number): number {
+  return Math.max(outerRadius - innerRadius, 0);
+}

package/src/geometry.ts

@@ -0,0 +1,151 @@
+import type { VireGlassOptics } from './material';
+
+/** Glass shape in dp. Circle and capsule are special cases of a rounded rectangle. */
+export type VireGlassGeometry = {
+  width: number;
+  height: number;
+  cornerRadius: number;
+};
+
+export const circleGeometry = (size: number): VireGlassGeometry => ({
+  width: size,
+  height: size,
+  cornerRadius: size / 2,
+});
+
+export const capsuleGeometry = (width: number, height: number): VireGlassGeometry => ({
+  width,
+  height,
+  cornerRadius: Math.min(width, height) / 2,
+});
+
+export const roundedRectGeometry = (
+  width: number,
+  height: number,
+  cornerRadius: number,
+): VireGlassGeometry => ({ width, height, cornerRadius });
+
+export const halfMinDp = (g: VireGlassGeometry) => Math.max(Math.min(g.width, g.height) / 2, 1);
+
+/** Viewport margin for a drop that overshoots past the finger: a fraction of the element's half
+ *  size beyond the drag travel itself. The drop overshoots the body by no more than `dragLimit`,
+ *  and stitching adds smoothing on top of that — this term covers it too. */
+export const MAX_STRETCH = 0.34;
+
+/**
+ * Bigger element, thicker glass: a stronger lens, a deeper shadow (docs/reference.md §1). Bevel
+ * and material thickness are specified for an element at a reference half-size and grow as the
+ * square root of size.
+ */
+const SIZE_REF_DP = 24;
+export const sizeGain = (g: VireGlassGeometry) =>
+  Math.min(Math.max(Math.sqrt(halfMinDp(g) / SIZE_REF_DP), 0.8), 2.4);
+
+/** A bevel wider than this fraction of the half-size breaks the SDF: the roundings converge in
+ *  the middle. */
+export const MAX_BEVEL_FRACTION = 0.65;
+
+export const bevelFraction = (g: VireGlassGeometry, o: VireGlassOptics) =>
+  Math.min(MAX_BEVEL_FRACTION, (o.bevelDp * sizeGain(g)) / halfMinDp(g));
+
+export const bevelDp = (g: VireGlassGeometry, o: VireGlassOptics) =>
+  Math.max(bevelFraction(g, o) * halfMinDp(g), 1);
+
+export const thicknessDp = (g: VireGlassGeometry, o: VireGlassOptics) =>
+  o.thicknessDp * sizeGain(g);
+
+/** Glass height right at the silhouette, a fraction of thickness: without it there's nothing at
+ *  the edge to bend the ray. */
+export const RIM_FRACTION = 0.85;
+
+export const rimDp = (g: VireGlassGeometry, o: VireGlassOptics) => thicknessDp(g, o) * RIM_FRACTION;
+
+/** Bigger element, deeper and wider shadow (M 7:14). */
+export const shadowReachDp = (g: VireGlassGeometry) =>
+  Math.min(Math.max(halfMinDp(g) * 0.65, 6), 36);
+
+/** How far the second morph shape reaches past the first one's bounds. Without this margin the
+ *  fused shape gets clipped by the canvas edge and the experiment shows the wrong thing. */
+export function morphReachDp(
+  g: VireGlassGeometry,
+  morph?: { offsetX: number; offsetY: number; width: number; height: number; smoothing: number },
+): number {
+  if (!morph || morph.smoothing <= 0) return 0;
+  return Math.max(
+    0,
+    Math.abs(morph.offsetX) + morph.width / 2 - g.width / 2,
+    Math.abs(morph.offsetY) + morph.height / 2 - g.height / 2,
+  );
+}
+
+/**
+ * Quantization step for the margin. The margin only needs to cover the sampling — its exact value
+ * doesn't matter, but changing it every frame is expensive: the native lens view gets re-laid-out
+ * and re-sets its `RenderEffect`. While dragging a panel or morphing, the margin used to drift
+ * continuously, and that produced visible stutter. Round up to the step — size changes rarely.
+ */
+const PAD_STEP = 8;
+const quantise = (v: number) => Math.ceil(v / PAD_STEP) * PAD_STEP;
+
+/**
+ * Margin around the lens view on each side: beyond it, the shader has nothing to sample.
+ *
+ * FOUR things have to fit in here. The refraction sample with aberrations. The blur radius —
+ * it also samples around the point. The gather radius — the rim picks it up from outside the
+ * shape, and without the margin it goes black exactly where it should be catching the
+ * surroundings. And drag travel: the lens view moves with the finger, but its bounds don't, and
+ * the sample falls off the edge, which is how layers from under the glass leak through.
+ */
+export function lensPadDp(
+  g: VireGlassGeometry,
+  o: VireGlassOptics,
+  morph?: Parameters<typeof morphReachDp>[1],
+  dragLimit = 0,
+): number {
+  const sampling = Math.max(o.blur, o.gatherRadiusDp);
+  const stretch = halfMinDp(g) * MAX_STRETCH;
+  return quantise(sampling + dragLimit + stretch + morphReachDp(g, morph) + 2);
+}
+
+/**
+ * Margin around the surface canvas: the shadow reaches outside the shape, and dragging shifts it
+ * further still.
+ *
+ * The multiplier is smaller than the shadow's full reach: under the finger, the shader for a
+ * rising element multiplies the radius by 1.55, and the very end of that tail falls outside the
+ * margin. Left that way on purpose — at the margin's edge it's at 1.2% alpha (2.5% before the
+ * shadow was softened), and raising the multiplier means growing every surface view's area. If
+ * that tail ever shows up on a device, fix it here.
+ */
+export function surfacePadDp(
+  g: VireGlassGeometry,
+  dragLimit = 0,
+  morph?: Parameters<typeof morphReachDp>[1],
+): number {
+  return quantise(shadowReachDp(g) * 1.2 + dragLimit + morphReachDp(g, morph) + 2);
+}
+
+/**
+ * SHADOW DENSITY BY WHAT'S UNDER THE ELEMENT. Reference 219 @11:47, verbatim: "increases the
+ * opacity of its shadow when it is over text… lowers the opacity of its shadow when it is over a
+ * solid light background." This is about content BEHIND THE ELEMENT, so it's a single value per
+ * element, not a field over the shadow's area.
+ *
+ * The law lives here, not at the bench: while it was baked into the web renderer, shadows on
+ * Android never adapted at all. The endpoints were checked against the reference by the depth of
+ * the dip under the element — docs/benchmarks.md.
+ */
+const SHADOW_FLAT = 0.8;
+const SHADOW_BUSY_GAIN = 6;
+const SHADOW_BUSY_RISE = 1.2;
+const SHADOW_STEP = 0.05;
+
+export function shadowOpacity(busy: number): number {
+  return SHADOW_FLAT + Math.min(Math.max(busy, 0) * SHADOW_BUSY_GAIN, SHADOW_BUSY_RISE);
+}
+
+/** Same thing for platforms where the measurement flows through state: quantized coarsely, like
+ *  the ambient color, otherwise every probe sample would trigger a surface repaint. */
+export function shadowOpacityFrom(sample: { busy: number }): number {
+  return Math.round(shadowOpacity(sample.busy) / SHADOW_STEP) * SHADOW_STEP;
+}

package/src/glass-scale.ts

@@ -0,0 +1,37 @@
+// User-facing glass transparency scale: iOS 26.1 gave a choice between two options ("default clear
+// look" or "tinted look which increases opacity of the material"), iOS 27 a continuous slider
+// "ultra clear → fully tinted", and apps get it without recompiling.
+//
+// It adjusts EFFECTS, not causes, and that's not a compromise. The cause "medium density" is
+// deliberately absent from the model: the glass has no color of its own, `bodyDensity` is derived
+// from absorption through the body and never exceeds 0.03, and the visible density is held by the
+// legibility requirement and scattering. A thickness scale would move a number that isn't visible
+// in the frame (measured by the `check:optics` gate).
+import type { VireGlassOptics } from './material';
+
+/** The point on the scale where the material stays exactly as it is today. */
+export const GLASS_SCALE_DEFAULT = 0.35;
+
+/** Body density at the "fully tinted" end: content under the glass must be hidden. */
+const TINTED_DENSITY = 0.9;
+
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/**
+ * `scale` 0 is ultra clear, 1 is fully tinted. Toward the transparent end, the legibility
+ * requirement and the dimming layer are relaxed (the user chose clarity); toward the tinted end,
+ * body density grows.
+ *
+ * Accessibility settings apply AFTER the scale: they set floors, and the user's chosen clarity
+ * does not override them (219 @18:45).
+ */
+export function applyGlassScale(optics: VireGlassOptics, scale: number): VireGlassOptics {
+  const s = clamp01(scale);
+  if (s === GLASS_SCALE_DEFAULT) return optics;
+  if (s < GLASS_SCALE_DEFAULT) {
+    const k = s / GLASS_SCALE_DEFAULT;
+    return { ...optics, legibility: optics.legibility * k, dimming: optics.dimming * k };
+  }
+  const k = (s - GLASS_SCALE_DEFAULT) / (1 - GLASS_SCALE_DEFAULT);
+  return { ...optics, bodyDensity: Math.max(optics.bodyDensity, TINTED_DENSITY * k) };
+}