vireglass 0.1.0

package/src/surface-shader.ts

@@ -0,0 +1,287 @@
+import { VG_FALLOFF, VG_SDF } from './sdf';
+
+/** Order matches `DEBUG_MODES` in `material.ts`: the index goes straight into `u_debug`. */
+export const SURFACE_SHADER = `
+uniform shader u_icon;
+/** App-colored content ON the glass — cover art, a thumbnail. A separate layer from the ink
+ *  mask: that one is single-channel and colored by polarity, this one carries its own color
+ *  as-is. */
+uniform shader u_overlay;
+
+uniform float2 u_center;
+uniform float2 u_halfSize;
+uniform float  u_corner;
+uniform float  u_bevel;
+uniform float  u_thickness;
+uniform float2 u_morphOffset;
+uniform float2 u_morphHalf;
+uniform float  u_morphCorner;
+uniform float  u_morphK;
+uniform float2 u_morph2Offset;
+uniform float2 u_morph2Half;
+uniform float  u_morph2Corner;
+
+uniform float  u_press;
+uniform float  u_active;
+/* 0 — the element sinks in under the finger, 1 — it rises into glass (reference §5). */
+uniform float  u_lift;
+
+uniform float  u_edgeDensity;
+uniform float  u_dispersion;
+uniform float  u_refraction;
+uniform float4 u_tint;
+uniform float  u_shadow;
+uniform float  u_shadowReach;
+uniform float3 u_ambient;
+uniform float  u_presence;
+uniform float  u_progress;
+uniform float  u_appear;
+uniform float  u_debug;
+
+uniform float  u_iconOn;
+uniform float  u_overlayOn;
+uniform float  u_iconScale;
+uniform float4 u_inkIdle;
+uniform float4 u_inkActive;
+uniform float2 u_touch;
+uniform float2 u_pull;
+uniform float  u_touchPress;
+uniform float  u_touchRadius;
+uniform float2 u_wave;
+
+${VG_SDF}
+
+const float VG_FALLOFF = ${VG_FALLOFF};
+
+// Tint density in the flat middle; at the bevel it's multiplied by u_edgeDensity.
+const float VG_BODY_DENSITY = 0.19;
+/* Fraction of the ambient hue in the shadow. The shadow has to stay a shadow, not a colored
+ *  blob. */
+const float VG_SHADOW_TINT = 1.0;
+// How much weaker the shadow is right at the outline than under the middle of the gap, and what
+// fraction of the offset it takes to reach full depth. In the reference the shadow's minimum
+// sits below the rim, not right at it.
+const float VG_GAP_LIGHT = 0.76;
+const float VG_GAP_REACH = 0.20;
+/* Depth of the ink beneath the surface, dp. The normal displaces it by exactly this much right
+ *  at the rim. */
+const float VG_INK_DEPTH = 4.0;
+/* Ink defocus under the finger (reference §6): a glyph loses its edge and drowns in milk. Given
+ * as a FRACTION of the touch blob, not a number: the blob already arrives in device units, so
+ * the radius automatically follows both screen density and the element's size. At rest it's
+ * zero, and the sample stays a single one. */
+const float VG_INK_DEFOCUS = 0.08;
+
+half4 vgPack(half3 c, float a) { return half4(c * half(a), half(a)); }
+
+// What bleeds into the shadow is the COLOR of the surroundings, not its brightness: the hue's own
+// lightness is subtracted out of it, otherwise the shadow pales and loses depth instead of
+// warming up. Strength is set by how much light there is around: over a nearly black backdrop
+// there's nothing to bleed into the shadow.
+float3 vgShadowTint(float3 ambient) {
+  float peak = max(max(ambient.r, ambient.g), max(ambient.b, 0.001));
+  float3 hue = ambient / peak;
+  float lumaWeights = dot(ambient, float3(0.2126, 0.7152, 0.0722));
+  return (hue - dot(hue, float3(0.2126, 0.7152, 0.0722))) * lumaWeights;
+}
+
+half3 vgHeat(float v) {
+  float x = clamp(v, 0.0, 1.0);
+  return half3(half(clamp(x * 2.2 - 0.2, 0.0, 1.0)),
+               half(clamp(1.0 - abs(x - 0.5) * 2.2, 0.0, 1.0)),
+               half(clamp(1.2 - x * 2.4, 0.0, 1.0)));
+}
+
+half4 main(float2 xy) {
+  float2 p = vgTouchWarp(xy - u_center, u_touch, u_pull, u_touchPress, u_touchRadius, u_wave.x, u_wave.y);
+
+  // Inverse deformation: stretch A along the pull vector, compression 1/sqrt(A) across it. This
+  // exact law mirrors the transform of the live backdrop under the canvas, otherwise the two
+  // would drift apart. There's NO motion geometry here — no pull, no press-driven bulge. All of
+  // that is done by a single wrapper transform, the same one that carries the native lens: the
+  // shader doesn't touch it, and two pipelines driving one motion would drift apart by a frame,
+  // making the layers visible as separate.
+
+  float halfMin = max(min(u_halfSize.x, u_halfSize.y), 1.0);
+  float bevel = max(u_bevel, 1.0);
+
+  float sd = vgScene(p, u_halfSize, u_corner, u_morphOffset, u_morphHalf, u_morphCorner, u_morphK,
+                u_morph2Offset, u_morph2Half, u_morph2Corner);
+  float t = vgBevelT(sd, bevel);
+  float2 n = vgSceneNormal(p, u_halfSize, u_corner, u_morphOffset, u_morphHalf, u_morphCorner, u_morphK,
+                u_morph2Offset, u_morph2Half, u_morph2Corner);
+  float3 N = normalize(float3(n * vgBevelSlope(t), 1.0));
+
+  // Progress is an active state turned into a field: the played fraction shines and glows
+  // exactly as much as an active element shines whole. This does NOT touch ink: recoloring text
+  // as the track advances would mean changing it mid-word.
+  float lit = max(u_active, vgProgress(p, u_halfSize, u_progress));
+
+  // The highlight and the rim are computed by the lens: reflection is a function of the
+  // surroundings, and only the lens can see them.
+
+  if (u_debug > 0.5) {
+    float inMask = 1.0 - smoothstep(-1.0, 1.0, sd);
+    if (u_debug < 1.5) {
+      float band = abs(fract(sd / (halfMin * 0.22)) - 0.5) * 2.0;
+      half3 c = sd < 0.0 ? half3(0.20, 0.62, 1.0) : half3(1.0, 0.42, 0.22);
+      return vgPack(c * half(0.25 + band * 0.75), 1.0);
+    }
+    if (u_debug < 2.5) { return vgPack(half3(1.0), inMask); }
+    if (u_debug < 3.5) { return vgPack(vgHeat(t), inMask); }
+    // Fresnel now lives in the lens; here we show its SHAPE — how grazing the view is.
+    if (u_debug < 4.5) { return vgPack(vgHeat(1.0 - clamp(N.z, 0.0, 1.0)), inMask); }
+    if (u_debug < 5.5) {
+      float push = pow(t, VG_FALLOFF) * u_refraction;
+      return vgPack(vgHeat(push), inMask);
+    }
+    if (u_debug < 6.5) { return half4(0.0); }
+    if (u_debug < 7.5) { return half4(0.0); }
+    // Dispersion is computed by the lens; here is the field it grows along.
+    if (u_debug < 8.5) { return vgPack(vgHeat(u_dispersion * t * t), inMask); }
+    if (u_debug < 9.5) { return vgPack(half3(N * 0.5 + 0.5), inMask); }
+    // spectral and adapt are shown by the LENS — the surface has to get out of the way.
+    return half4(0.0);
+  }
+
+  // The shadow and the halo live OUTSIDE the shape: inside, their place is taken by the glass
+  // itself. Separation from the content rests entirely on the shadow — without it the surface
+  // would sit ON the picture, not above it. The shadow only lives at the rim and outside it: at
+  // sd < −1 the outside multiplier is already zero. Computing it deep inside the shape would be
+  // a wasted FULL SDF evaluation for every such pixel, and the body covers almost the whole
+  // area. The branch here is on the coordinate, but only the threads right at the rim actually
+  // diverge.
+  float shade = 0.0;
+  float halo = 0.0;
+  if (sd > -1.0) {
+    float outside = smoothstep(-1.0, 1.0, sd);
+    // Under the finger a button moves TOWARD the backdrop, and the shadow tightens: it's exactly
+    // the gap between the two. A control rising into glass (a switch knob, a slider handle —
+    // reference §5) moves AWAY from it, and then the shadow spreads out instead. Only the app
+    // knows which one applies, so the direction arrives as a fraction: 0 is sinking in, the way
+    // every element behaved before this rule existed.
+    float reach = u_shadowReach * (1.0 + mix(-0.25, 0.55, u_lift) * u_press);
+    // The shadow is soft and wide, shifted downward (M 11:58): it's what holds the element's
+    // separation from the content.
+    float sdDrop = vgScene(p - float2(0.0, reach * 0.35), u_halfSize, u_corner,
+                           u_morphOffset, u_morphHalf, u_morphCorner, u_morphK,
+                u_morph2Offset, u_morph2Half, u_morph2Corner);
+    float amb = 1.0 - smoothstep(-reach * 0.3, reach, sdDrop);
+    // THE GAP UNDER A RAISED ELEMENT IS LIT: right at the outline the shadow is WEAKER than
+    // further down. Otherwise the minimum sits right against the silhouette — both parts of the
+    // shadow are monotonic in distance.
+    float gap = smoothstep(0.0, max(reach * VG_GAP_REACH, 1.0), max(sd, 0.0));
+    shade = amb * amb * 0.13 * mix(VG_GAP_LIGHT, 1.0, gap) * outside * u_shadow * u_appear;
+    halo = 1.0 - smoothstep(0.0, reach * 0.30, max(sd, 0.0));
+    halo = halo * halo * lit * 0.10 * outside * u_appear;
+  }
+
+  if (sd > 1.0) {
+    // Ambient light bleeds into the shadow (219 @8:22): it isn't a black hole, it's tinted by
+    // whatever lies nearby. Otherwise an element over colored content would hang over a gray
+    // blob.
+    half3 spill = max(half3(half(halo)) + half3(vgShadowTint(u_ambient)) * half(VG_SHADOW_TINT * shade * (1.0 - halo)), half3(0.0));
+    return half4(spill, half(halo + shade * (1.0 - halo)));
+  }
+
+  float density = u_tint.w;
+  float inner = clamp(-sd / halfMin, 0.0, 1.0);
+  half3 col = half3(u_tint.rgb);
+
+  // The tint is LIGHT and weak, not dark: dark glass over dark content disappears, and has to be
+  // held together with a heavy rim — which makes the surface read as a chrome bead. Tint density
+  // at the bevel is a separate value: physically the bevel bends light harder, but it doesn't
+  // get hazier. Coupled together, the two produced a milky ring around the whole outline.
+  float body = mix(VG_BODY_DENSITY, VG_BODY_DENSITY * u_edgeDensity, smoothstep(0.10, 0.62, t)) * density;
+  float vignette = smoothstep(0.15, 1.0, inner) * 0.19 * density;
+  // There's NO density boost on press here. It was meant as "the element stands out more under
+  // the finger," but it pulls the body toward the tint, and the tint depends on polarity: over a
+  // light backdrop (dark polarity) press ended up DARKENING the element. Presence is shown
+  // instead by the vgTouchWarp field's deformation and the highlight blooming below — neither
+  // cares about the sign of polarity.
+  float a = max(body, vignette);
+
+  // Active state does NOT touch the body's color. Mixing in a fixed gray here flipped the
+  // effect's sign depending on the backdrop: over dark the element lightened, over light it
+  // darkened, for the exact same state. Active state is shown instead by the highlight and rim
+  // lighting above: neither cares about the backdrop.
+
+  // THE ICON SITS BENEATH THE SURFACE, it isn't stuck on top of it: it used to be mixed in last,
+  // over the highlight, and read as a flat sticker on volumetric glass. At the rim the normal
+  // displaces it, like everything seen through the glass, while the highlight sits ON TOP — it
+  // lives on the surface itself.
+  //
+  // There is NO shadow under the icon here. It used to be made from the difference of two offset
+  // mask samples and produced a second outline along the edge — the icon's borders looked
+  // ragged.
+  // THE INK'S SHIFT IS SET BY ITS OWN DEPTH, NOT BY BEVEL WIDTH. The ink sits right at the
+  // surface, and it's displaced by exactly the thin layer of glass above it — not by how wide a
+  // bevel this particular piece of glass happens to have. It used to be a fraction of the bevel:
+  // on thin glass the shift came out to 4 dp and everything lined up, but on thick glass it was
+  // 8, and cover art inset from the edge by 6 stretched toward the rim and spilled past its
+  // bounds. The ceiling is absolute: ink has one depth regardless of the glass.
+  float2 inkShift = n * (min(u_bevel * 0.5, VG_INK_DEPTH) * t);
+  float2 inkUv = u_center + p - inkShift;
+
+  // INK LOSES SHARPNESS UNDER THE FINGER (reference §6): in the reference, a glyph under
+  // pressure drowns in milk rather than simply getting lighter. This branch is uniform across
+  // the whole element: press arrives as a uniform, so defocus costs nothing while the element
+  // isn't being touched.
+  float defocus = VG_INK_DEFOCUS * u_touchRadius * u_touchPress;
+  float2 inkDx = float2(defocus, 0.0);
+  float2 inkDy = float2(0.0, defocus);
+
+  half4 ink;
+  half4 over;
+  if (defocus > 0.01) {
+    // A cross around the center with double weight in the middle: the ink mask is
+    // high-contrast, and four samples are enough for a stroke to stop holding its edge.
+    ink = (u_icon.eval((inkUv - inkDx) * u_iconScale)
+         + u_icon.eval((inkUv + inkDx) * u_iconScale)
+         + u_icon.eval((inkUv - inkDy) * u_iconScale)
+         + u_icon.eval((inkUv + inkDy) * u_iconScale)
+         + u_icon.eval(inkUv * u_iconScale) * 2.0) * half(u_iconOn / 6.0);
+    // Colored content lives in the same plane as the ink and blurs together with it: different
+    // sharpness for two layers in one plane would read as a defect, not a press.
+    over = (u_overlay.eval((inkUv - inkDx) * u_iconScale)
+          + u_overlay.eval((inkUv + inkDx) * u_iconScale)
+          + u_overlay.eval((inkUv - inkDy) * u_iconScale)
+          + u_overlay.eval((inkUv + inkDy) * u_iconScale)
+          + u_overlay.eval(inkUv * u_iconScale) * 2.0) * half(u_overlayOn * u_appear / 6.0);
+  } else {
+    ink = u_icon.eval(inkUv * u_iconScale) * half(u_iconOn);
+    over = u_overlay.eval(inkUv * u_iconScale) * half(u_overlayOn * u_appear);
+  }
+
+  // The backing under the ink is held by the LENS (body density from the probe), not the
+  // surface: legibility is a property of the material, and computing it here a second time
+  // would give two different answers to one question.
+
+  // Layers are composited premultiplied-over: in straight alpha, a nearly transparent dark body
+  // used to pull the color of semi-transparent ink and the finger's light toward itself — letter
+  // edges grayed out, pressing darkened things.
+  half3 pm = col * half(a);
+  half inkA = ink.g * half(mix(0.82, 1.0, u_active) * u_appear);
+  half3 inkCol = mix(half3(u_inkIdle.rgb), half3(u_inkActive.rgb), half(u_active));
+  pm = pm * (1.0 - inkA) + inkCol * inkA;
+  a = a + float(inkA) * (1.0 - a);
+
+  // COLORED CONTENT LIVES IN THE SAME PLACE AS THE INK — inside the material, at the same
+  // coordinate. Otherwise deformation would carry them apart: on press, the title and artist
+  // name would shake together with the surface while the cover art stayed put, because it used
+  // to be a separate layer on top of the glass. Polarity doesn't touch it — it has its own
+  // color, and there's nothing to swap it for.
+  pm = pm * (1.0 - over.a) + over.rgb * over.a;
+  a = a + float(over.a) * (1.0 - a);
+
+  // Light from the finger is gathered by the LENS: it's a concentration of the surroundings, not
+  // the glass's own whiteness. The surface is left with only what the glass spills outward — the
+  // halo above.
+
+  float mask = 1.0 - smoothstep(-1.0, 1.0, sd);
+  pm = clamp(pm, half3(0.0), half3(1.0)) * half(mask);
+  a *= mask;
+  pm = max(pm + half3(vgShadowTint(u_ambient)) * half(VG_SHADOW_TINT * shade * (1.0 - a)), half3(0.0));
+  return half4(pm, half(a + shade * (1.0 - a)));
+}
+`;

package/src/targets/agsl.ts

@@ -0,0 +1,8 @@
+// Android target. AGSL and SkSL are the same language, so `lens-shader.ts`/`surface-shader.ts`
+// already assemble the finished AGSL text as a string (SDF + body via `${VG_SDF}`) — there's
+// nothing to translate. The identity function here fixes the "input = output" contract as a
+// target in its own right, symmetric with `targets/glsl.ts`, and guards the native path against
+// an accidental edit in some future refactor.
+export function toAGSL(shaderSource: string): string {
+  return shaderSource;
+}

package/src/targets/glsl.ts

@@ -0,0 +1,140 @@
+// WebGL2 target. Translates the same AGSL text (SDF + body, see `targets/agsl.ts`) into GLSL
+// ES 3.0. Each conversion rule is its own function with its own test in
+// `__tests__/targets.test.ts`. Three spots are NOT mechanical: the coordinate origin, units of
+// measure (settled in the web renderer's own setup, not here), and sampler filtering (also the
+// renderer's concern). What's here is text conversion only.
+
+/**
+ * The sampler-size uniform's name, for translating `NAME.eval(coord)` → `texture(NAME, coord / SIZE)`.
+ * A new uniform — there's no equivalent in AGSL: `.eval()` has the size implicitly known to the
+ * shader, while GLSL's `texture()` needs a normalized coordinate. One per `uniform shader`/
+ * `uniform sampler2D`, its name derived from the sampler's name rather than hardcoded.
+ */
+function sizeUniformName(sampler: string): string {
+  return sampler.startsWith('u_') ? `${sampler}Size` : `u_${sampler}Size`;
+}
+
+/** float2/float3/float4 → vec2/vec3/vec4. */
+export function convertVecTypes(src: string): string {
+  return src.replace(/\bfloat([234])\b/g, 'vec$1');
+}
+
+/** half/half2/half3/half4 → float/vec2/vec3/vec4, including half(x) → float(x) casts. */
+export function convertHalfTypes(src: string): string {
+  return src.replace(/\bhalf([234])\b/g, 'vec$1').replace(/\bhalf\b/g, 'float');
+}
+
+/** `uniform shader NAME;` → `uniform sampler2D NAME;` + a new `uniform vec2 <sizeUniform>;`. */
+export function convertShaderUniforms(src: string): string {
+  return src.replace(/uniform\s+shader\s+(\w+)\s*;/g, (_match, name: string) => {
+    return `uniform sampler2D ${name};\nuniform vec2 ${sizeUniformName(name)};`;
+  });
+}
+
+/**
+ * `NAME.eval(coord)` → `texture(NAME, (coord) / <sizeUniform>)` for each declared
+ * `uniform sampler2D`. The bounds of `coord` are found by scanning parens, not with a regex: the
+ * arguments are nested calls (`content.eval(vgInContent(s + dR - e))`) with commas and
+ * parentheses inside.
+ */
+export function convertEvalCalls(src: string): string {
+  const samplers = new Set<string>();
+  const declRe = /uniform\s+sampler2D\s+(\w+)\s*;/g;
+  for (let m = declRe.exec(src); m; m = declRe.exec(src)) samplers.add(m[1]);
+  if (samplers.size === 0) return src;
+
+  const callRe = /(\w+)\.eval\(/g;
+  let out = '';
+  let cursor = 0;
+  for (let m = callRe.exec(src); m; m = callRe.exec(src)) {
+    const name = m[1];
+    if (!samplers.has(name)) continue;
+    const argStart = m.index + m[0].length;
+    let depth = 1;
+    let i = argStart;
+    while (i < src.length && depth > 0) {
+      if (src[i] === '(') depth += 1;
+      else if (src[i] === ')') depth -= 1;
+      i += 1;
+    }
+    const args = src.slice(argStart, i - 1);
+    out += src.slice(cursor, m.index);
+    out += `texture(${name}, (${args}) / ${sizeUniformName(name)})`;
+    cursor = i;
+    callRe.lastIndex = i;
+  }
+  out += src.slice(cursor);
+  return out;
+}
+
+/**
+ * Early `return <expression>;` inside `main` → `fragColor = <expression>; return;`. Takes ONLY
+ * the body of main (see `convertEntryPoint`) — ordinary `return`s in helper functions live
+ * outside this text and are untouched. Expressions never contain a `;` of their own (shaders have
+ * none — the only `;` lives inside `for(...)`, which isn't a return), so `[^;]+` is safe.
+ */
+export function convertReturns(mainBody: string): string {
+  return mainBody.replace(/\breturn\s+([^;]+);/g, 'fragColor = $1; return;');
+}
+
+const ENTRY_RE = /half4\s+main\s*\(\s*float2\s+(\w+)\s*\)\s*\{/;
+
+/**
+ * `half4 main(float2 xy) { ... }` → `void main() { vec2 xy = <Y-flipped coordinate>; ...; }`.
+ * AGSL gives `xy` in screen pixels, top-left origin, y down; `gl_FragCoord` is bottom-left
+ * origin, y up. The flip via `u_resolution.y - gl_FragCoord.y` restores the original convention
+ * (both coordinate systems center the pixel at `+0.5`, so no X shift or constant is needed).
+ * `out vec4 fragColor` and `uniform vec2 u_resolution` are declared in the prologue (`addPrologue`).
+ */
+export function convertEntryPoint(src: string): string {
+  const match = ENTRY_RE.exec(src);
+  if (!match) {
+    throw new Error('vireglass/targets/glsl: entry point "half4 main(float2 xy)" not found');
+  }
+  const bodyStart = match.index + match[0].length;
+  let depth = 1;
+  let i = bodyStart;
+  while (i < src.length && depth > 0) {
+    if (src[i] === '{') depth += 1;
+    else if (src[i] === '}') depth -= 1;
+    i += 1;
+  }
+  const bodyEnd = i - 1;
+  const param = match[1];
+  const body = convertReturns(src.slice(bodyStart, bodyEnd));
+  const head = src.slice(0, match.index);
+  const tail = src.slice(i);
+  return (
+    `${head}void main() {\n` +
+    `  vec2 ${param} = vec2(gl_FragCoord.x, u_resolution.y - gl_FragCoord.y);\n` +
+    `${body}}${tail}`
+  );
+}
+
+/** `#version 300 es` + `precision highp float;` — no equivalent in AGSL, WebGL2 requires them as
+ *  the file's first lines. `out vec4 fragColor` and `uniform vec2 u_resolution` ride along here
+ *  too: both new, with no counterpart in the source, needed by exactly one entry point
+ *  (`convertEntryPoint`). */
+export function addPrologue(src: string): string {
+  return (
+    '#version 300 es\n' +
+    'precision highp float;\n\n' +
+    'out vec4 fragColor;\n' +
+    'uniform vec2 u_resolution;\n\n' +
+    src
+  );
+}
+
+/** Full translation AGSL/SkSL → GLSL ES 3.0. Order matters: the entry point is found by its
+ *  literal AGSL signature BEFORE type conversion, otherwise `half4 main(float2 xy)` can't be
+ *  found. */
+export function toGLSL(shaderSource: string): string {
+  let out = shaderSource;
+  out = convertEntryPoint(out);
+  out = convertShaderUniforms(out);
+  out = convertEvalCalls(out);
+  out = convertVecTypes(out);
+  out = convertHalfTypes(out);
+  out = addPrologue(out);
+  return out;
+}

package/src/touch-response.ts

@@ -0,0 +1,195 @@
+// The element's response to a finger — PART OF THE MATERIAL, not the app: the springs here
+// describe what the medium feels like, exactly the way ior describes what it looks like through.
+// Keeping them with the consumer would mean web and Android end up with two different glasses
+// under one name.
+//
+// It's the FIELD around the touch point that deforms (vgTouchWarp in sdf.ts), so four values are
+// computed here: where it was touched, how far it's being dragged, how deep the press is, and
+// what wave is currently running.
+//
+// The key point: drag is anchored to the touch BLOB. Pull the right edge and the right edge
+// moves, the left stays put; the finger has area, not a point — the plateau inside `vgTouchWarp`.
+// Scaling the shape's bounding box isn't an option: that would make a rightward pull also bulge
+// the left side, which liquid doesn't do.
+//
+//   PRESS is viscous: it dents shallow and releases slowly.
+//   DRAG is thick: the body noticeably lags the finger, travel is short, and on release it snaps
+//   back quickly with almost no overshoot. A wide, springy overshoot would be liquid jelly, not
+//   dense glass.
+//   WAVE: touch and lift-off each throw a short ring that decays within a quarter second.
+
+export type DeformSample = {
+  /** Touch point relative to the element's center, CSS pixels. */
+  touchX: number;
+  touchY: number;
+  pullX: number;
+  pullY: number;
+  press: number;
+  active: number;
+  /** Wave amplitude in CSS pixels and its phase in turns. */
+  waveAmp: number;
+  wavePhase: number;
+};
+
+const HOLD_STIFFNESS = 260;
+const HOLD_DAMPING = 46;
+/** Release is stiffer than hold, but damping is high: a dense medium snaps back fast with almost
+ *  no overshoot. A visible overshoot would be liquid jelly, not dense glass. */
+const RELEASE_STIFFNESS = 420;
+const RELEASE_DAMPING = 34;
+
+const PRESS_ATTACK = 0.07;
+const PRESS_RELEASE = 0.16;
+
+/** The wave is short and weak: in a viscous medium ripples decay within a quarter second rather
+ *  than oscillating. */
+const WAVE_DECAY = 0.22;
+const WAVE_TURNS_PER_SECOND = 3.0;
+
+export function createDeform() {
+  let touchX = 0;
+  let touchY = 0;
+  let targetTouchX = 0;
+  let targetTouchY = 0;
+  let pullX = 0;
+  let pullY = 0;
+  let vx = 0;
+  let vy = 0;
+  let targetX = 0;
+  let targetY = 0;
+  let held = false;
+  let press = 0;
+  let active = 0;
+  let waveAmp = 0;
+  let wavePhase = 0;
+
+  /** `x`, `y` — touch point relative to the element's center, CSS pixels. */
+  function grab(x: number, y: number, waveStart: number): void {
+    // Rest is checked BEFORE the grab: idle() looks at !held, and after `held = true` it's
+    // always false — the point would then jump even on a first touch of a resting element.
+    const atRest = idle();
+    held = true;
+    targetTouchX = x;
+    targetTouchY = y;
+    // On a resting element the finger lands instantly; if it hasn't settled yet from the
+    // previous touch, the point travels there over a couple of frames. An instant jump tears the
+    // deformation, and on rapid taps that reads as jitter.
+    if (atRest) {
+      touchX = x;
+      touchY = y;
+    }
+    targetX = 0;
+    targetY = 0;
+    // Impulses ADD UP rather than restart, and phase isn't reset: resetting it would cut off a
+    // running wave mid-period, which is exactly what causes a jolt on rapid clicks.
+    waveAmp = Math.min(waveAmp + waveStart, waveStart * 1.6);
+  }
+
+  function drag(dx: number, dy: number, limit: number): void {
+    if (!held) return;
+    const len = Math.hypot(dx, dy);
+    // Travel saturates rather than clips: near the limit the finger keeps moving while the field
+    // barely does — that's how a thick liquid behaves once it hits its limit.
+    const scale = len > 1e-3 ? (limit * Math.tanh(len / limit)) / len : 0;
+    targetX = dx * scale;
+    targetY = dy * scale;
+  }
+
+  /** Lifting the finger throws a second wave — weaker than the one from touching down. */
+  function release(waveStart: number): void {
+    held = false;
+    targetX = 0;
+    targetY = 0;
+    waveAmp = Math.min(waveAmp + waveStart, waveStart * 2);
+  }
+
+  function integrate(dt: number): void {
+    const k = held ? HOLD_STIFFNESS : RELEASE_STIFFNESS;
+    const c = held ? HOLD_DAMPING : RELEASE_DAMPING;
+    vx += (k * (targetX - pullX) - c * vx) * dt;
+    vy += (k * (targetY - pullY) - c * vy) * dt;
+    pullX += vx * dt;
+    pullY += vy * dt;
+
+    const pressTarget = held ? 1 : 0;
+    const tau = held ? PRESS_ATTACK : PRESS_RELEASE;
+    press += (pressTarget - press) * (1 - Math.exp(-dt / tau));
+    active += (pressTarget - active) * (1 - Math.exp(-dt / 0.09));
+
+    // The touch point catches up to the finger fast, but not instantly — see grab().
+    const follow = 1 - Math.exp(-dt / 0.045);
+    touchX += (targetTouchX - touchX) * follow;
+    touchY += (targetTouchY - touchY) * follow;
+
+    wavePhase += dt * WAVE_TURNS_PER_SECOND;
+    waveAmp *= Math.exp(-dt / WAVE_DECAY);
+    if (waveAmp < 0.01) waveAmp = 0;
+  }
+
+  /**
+   * The step is fixed, the frame isn't: on a software renderer there can be as few as ten frames
+   * a second, and integrating "however much time passed" makes the response lag behind real time
+   * (and at a large step the spring can even diverge). So time is caught up in sub-steps.
+   */
+  function step(dt: number): void {
+    let rest = Math.min(Math.max(dt, 0), 0.25);
+    const h = 1 / 120;
+    while (rest > 1e-6) {
+      const slice = Math.min(h, rest);
+      integrate(slice);
+      rest -= slice;
+    }
+    // Settled means exactly at rest. The `idle()` threshold stops rendering, but the values
+    // themselves only approach zero asymptotically, and the element would stay forever very
+    // slightly deformed: invisible to the eye, but a frame-vs-reference comparison would flag the
+    // mismatch forever.
+    if (idle()) {
+      pullX = 0;
+      pullY = 0;
+      vx = 0;
+      vy = 0;
+      press = 0;
+      active = 0;
+      wavePhase = 0;
+    }
+  }
+
+  /** Whether the element has settled — the bench uses this to decide whether to keep drawing frames. */
+  function idle(): boolean {
+    return (
+      !held &&
+      Math.abs(pullX) < 0.05 &&
+      Math.abs(pullY) < 0.05 &&
+      Math.hypot(vx, vy) < 0.5 &&
+      press < 0.004 &&
+      active < 0.004 &&
+      waveAmp === 0
+    );
+  }
+
+  function sample(): DeformSample {
+    return { touchX, touchY, pullX, pullY, press, active, waveAmp, wavePhase };
+  }
+
+  return { grab, drag, release, step, idle, sample };
+}
+
+/**
+ * RAISING INTO GLASS (reference §5, M 4:10–4:30). A control that isn't glass at rest — a switch
+ * knob, a slider handle — stops being frosted under the finger and becomes a lens: whatever is
+ * beneath it shows through.
+ *
+ * Glass comes in FASTER than frost leaves: the two fractions overlap, otherwise midway through
+ * the transition the backdrop flashes through the knob for an instant — a hole where the control
+ * should be.
+ *
+ * Lifting off the backdrop is NOT part of this. The shader's `u_lift` is a direction ("this kind
+ * of element sinks in or rises"), not a magnitude — how far it has already risen is carried by
+ * the press value that `u_lift` gets multiplied by. Returning a third fraction here would mean
+ * multiplying press by itself — which is exactly what happened the first time the web bench wired
+ * this up.
+ */
+export function raiseIntoGlass(press: number): { glass: number; solid: number } {
+  const t = press < 0 ? 0 : press > 1 ? 1 : press;
+  return { glass: Math.pow(t, 0.6), solid: 1 - Math.pow(t, 1.4) };
+}