vireglass 0.1.0 → 2.0.0

package/src/adapters.ts

@@ -1,3 +1,4 @@
+import { ACCENT, MORPH } from './law';
 import {
   bevelDp,
   bevelFraction,
@@ -9,6 +10,7 @@ import {
   type VireGlassGeometry,
 } from './geometry';
 import { LENS_SHADER } from './lens-shader';
+import { neckToBridge } from './sdf';
 import { debugIndex, type VireGlassDebugMode, type VireGlassOptics } from './material';
 
 /** Smooth union with a second shape — bench morphing experiment only. */
@@ -50,7 +52,7 @@ const NO_PROGRESS = -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;
+export const ACCENT_AMOUNT = ACCENT.amount;
 const NO_ACCENT = [0, 0, 0, 0] as const;
 
 
@@ -340,7 +342,33 @@ export const OVERLAY_UNIFORMS = ['u_overlayOn'] as const;
  * 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;
+
+
+/**
+ * How wide the neck between two lobes has to be: enough to soften the seam on a large element, and
+ * enough to actually SPAN whatever is between them. The second term is the one that was missing.
+ */
+function neckFor(
+  half: number,
+  aw: number,
+  ah: number,
+  bw: number,
+  bh: number,
+  offsetX: number,
+  offsetY: number,
+): number {
+  // Surface-to-surface, measured between the bounding boxes. The rounded corners put the true
+  // surfaces slightly further apart, so this errs toward a wider neck, which is the safe side.
+  const gx = Math.abs(offsetX) - (aw + bw) / 2;
+  const gy = Math.abs(offsetY) - (ah + bh) / 2;
+  const gap = Math.hypot(Math.max(gx, 0), Math.max(gy, 0));
+  // Capped at the narrowest of the two bodies. A neck wider than what it joins is not a neck, and
+  // past that width the honest answer is that these are two things rather than one — a menu that
+  // has finished leaving its button, two controls too far apart to be a segmented control. Being
+  // separate is a legitimate state; being joined by a blob larger than either shape is not.
+  const widest = Math.min(aw, ah, bw, bh);
+  return Math.min(Math.max(half * MORPH.neck, neckToBridge(gap) * MORPH.fuse), widest);
+}
 
 export function morphBetween(
   a: VireGlassGeometry,
@@ -357,6 +385,46 @@ export function morphBetween(
     width: b.width,
     height: b.height,
     cornerRadius: b.cornerRadius,
-    smoothing: half * MORPH_NECK * Math.min(t, 1),
+    smoothing: neckFor(half, a.width, a.height, b.width, b.height, offsetX, offsetY) * Math.min(t, 1),
+  };
+}
+
+/**
+ * MITOSIS: the second shape grows OUT OF the first and travels to its place, instead of appearing
+ * beside it at full size. A menu coming out of its button, a control dividing into segments.
+ *
+ * `morphBetween` is the other half — two shapes that are both already where they belong, fusing
+ * into one body — and run backwards it is meiosis, the neck thinning until it breaks. What neither
+ * of them may do is pop: at any `t` above zero this returns one continuous body, because that is
+ * the whole of what the reference says a material transition is.
+ *
+ * The choreography stays the host's: what the shapes MEAN is the app's business. How a silhouette
+ * emerges from another silhouette is the material's, the same way the spring under a finger is.
+ */
+export function morphOutOf(
+  source: VireGlassGeometry,
+  target: VireGlassGeometry,
+  offsetX: number,
+  offsetY: number,
+  t: number,
+): VireGlassMorph | undefined {
+  if (t <= 0) return undefined;
+  const k = Math.min(t, 1);
+  // At t = 0 the lobe IS the parent, in the parent's place: the transition starts from one body and
+  // never has a first frame in which a second one exists. The parent's own surface is what the neck
+  // attaches to, so nothing has to be budded off to give it something to hold.
+  const width = source.width + (target.width - source.width) * k;
+  const height = source.height + (target.height - source.height) * k;
+  const cornerRadius = source.cornerRadius + (target.cornerRadius - source.cornerRadius) * k;
+  const half = Math.min(halfMinDp(source), Math.min(width, height) / 2);
+  return {
+    offsetX: offsetX * k,
+    offsetY: offsetY * k,
+    width,
+    height,
+    cornerRadius,
+    // The lobe travels as it grows, so the span changes every frame and the neck is measured
+    // against where the lobe actually is, not against where it will end up.
+    smoothing: neckFor(half, source.width, source.height, width, height, offsetX * k, offsetY * k),
   };
 }

package/src/appear.ts

@@ -0,0 +1,45 @@
+// Materialising in and out (docs/reference.md §1, 219 @2:55): "Instead of fading, Liquid Glass
+// objects materialize in and out by gradually modulating the light bending and lensing, ensuring a
+// graceful transition that preserves the optical integrity of the material."
+//
+// So an element must not arrive by opacity. Fading it leaves a half-transparent picture OF glass;
+// modulating the lens leaves glass that is not yet bending much light. The difference is visible:
+// a faded element shows the backdrop through a veil, a materialising one shows it undistorted.
+//
+// JS twin of what `u_appear` multiplies in the lens: the lens strength itself, the frost, the
+// body, the dimming layer and the rim's light. Everything that makes the material present, and
+// nothing that makes it opaque.
+import type { VireGlassOptics } from './material';
+
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/**
+ * `t` of 0 is an element indistinguishable from the backdrop beneath it; 1 is the material at
+ * full strength. Between them the glass bends progressively more light.
+ */
+export function applyAppear(optics: VireGlassOptics, t: number): VireGlassOptics {
+  const a = clamp01(t);
+  if (a === 1) return optics;
+  return {
+    ...optics,
+    refraction: optics.refraction * a,
+    blur: optics.blur * a,
+    bodyDensity: optics.bodyDensity * a,
+    dimming: optics.dimming * a,
+    edgeLight: optics.edgeLight * a,
+    // A floor on how far the element must stand out from its backdrop (§3). Left alone it holds
+    // the element visible at t = 0, which is the opposite of what materialising means.
+    presence: optics.presence * a,
+    // The spectral trio is lensing too — §1's "light bending and lensing" is not only the
+    // displacement. The fringe map and the per-channel split are drawn from these, and a filter
+    // graph that still paints them is an element that is not there but is casting a rainbow.
+    dispersion: optics.dispersion * a,
+    iridescence: optics.iridescence * a,
+    diffraction: optics.diffraction * a,
+    tintStrength: optics.tintStrength * a,
+    // Legibility is a REQUIREMENT, not an effect: an element still arriving has no ink on it yet,
+    // and holding a demand it cannot meet would darken the body exactly while it should be
+    // clearing. It fades with the rest.
+    legibility: optics.legibility * a,
+  };
+}

package/src/concentric.ts

@@ -23,3 +23,69 @@ export function concentricRadius(outerRadius: number, inset: number, minimum = 0
 export function concentricInset(outerRadius: number, innerRadius: number): number {
   return Math.max(outerRadius - innerRadius, 0);
 }
+
+/**
+ * The three shape types the design system builds concentric layouts from (356 @3:42): "fixed
+ * shapes have a constant corner radius. Capsules use a radius that's half the height of the
+ * container. And concentric shapes calculate their radius by subtracting padding from the
+ * parent's."
+ *
+ * Naming them is the point. 356 @5:09: "using the three shape types we covered earlier helps keep
+ * your components aligned with the system." A host that only has a number has to decide what that
+ * number means every time the layout changes; a host that has the type gets the number recomputed
+ * for it.
+ */
+export type ShapeSpec =
+  | { type: 'fixed'; radius: number }
+  | { type: 'capsule' }
+  /**
+   * `fallback` is 356 @6:00: "a neat trick for managing components that need to work both inside a
+   * container and on their own: use a concentric shape with a fallback radius. The concentric value
+   * adapts when nested, and the fallback kicks in when the component stands alone."
+   *
+   * It is not the same as `minimum`. A minimum is a floor that applies while nested and breaks
+   * concentricity on purpose; a fallback applies only when there is no parent to be concentric
+   * with, and never overrides a parent that exists.
+   */
+  | { type: 'concentric'; inset: number; minimum?: number; fallback?: number };
+
+/** What is around a shape, when there is something around it. */
+export type ShapeParent = { cornerRadius: number };
+
+/**
+ * The corner radius a shape takes in the place it finds itself. `height` is the shape's own, which
+ * is what a capsule's radius is measured from; `parent` is absent when the shape stands alone.
+ */
+export function resolveShape(spec: ShapeSpec, height: number, parent?: ShapeParent): number {
+  switch (spec.type) {
+    case 'fixed':
+      return Math.max(spec.radius, 0);
+    case 'capsule':
+      return Math.max(height, 0) / 2;
+    case 'concentric':
+      return parent
+        ? concentricRadius(parent.cornerRadius, spec.inset, spec.minimum)
+        : Math.max(spec.fallback ?? 0, 0);
+  }
+}
+
+/**
+ * Whether two nested shapes are concentric, and which way they are wrong when they are not.
+ * 356 @5:19: "keep an eye out for corners that feel too pinched — or flared. They can create
+ * tension and break the sense of balance."
+ *
+ * Pinched is an inner radius smaller than concentricity asks for: the gap between the corners
+ * widens through the curve. Flared is larger: the gap narrows and the corners crowd each other.
+ * The defect is visible to the eye and usually goes unnamed, which is why this names it.
+ */
+export function concentricFit(
+  outerRadius: number,
+  inset: number,
+  innerRadius: number,
+  tolerance = 0.5,
+): 'concentric' | 'pinched' | 'flared' {
+  const want = concentricRadius(outerRadius, inset);
+  if (innerRadius < want - tolerance) return 'pinched';
+  if (innerRadius > want + tolerance) return 'flared';
+  return 'concentric';
+}

package/src/dom/body.ts

@@ -0,0 +1,98 @@
+// 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
+// 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 type { VireGlassOptics } from '../material';
+
+const {
+  capLoose: BODY_CAP_LOOSE,
+  capTight: BODY_CAP_TIGHT,
+  tintDark: TINT_DARK,
+  tintLight: TINT_LIGHT,
+  groundSpan: GROUND_SPAN,
+  busyEdge: BUSY_EDGE,
+  darkSideFrom: DARK_SIDE_FROM,
+  darkSideTo: DARK_SIDE_TO,
+  maxDemand: MAX_DEMAND,
+} = BODY;
+
+const clamp = (v: number, lo: number, hi: number) => (v < lo ? lo : v > hi ? hi : v);
+const mix = (a: number, b: number, t: number) => a + (b - a) * t;
+
+function smoothstep(edge0: number, edge1: number, x: number): number {
+  const t = clamp((x - edge0) / (edge1 - edge0), 0, 1);
+  return t * t * (3 - 2 * t);
+}
+
+/** Only the two figures the law reads — the same narrowing `shadowOpacityFrom` uses. */
+export type BodyBackdrop = { luma: number; busy: number };
+
+export type GlassBody = {
+  /** How much medium stands between the backdrop and the eye, 0…1. */
+  density: number;
+  /** Lightness the body tints toward. */
+  tintLuma: number;
+};
+
+/**
+ * `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
+ * glass dip toward the middle while a recolor is in flight.
+ */
+export function resolveBody(optics: VireGlassOptics, sample: BodyBackdrop, ink: number): GlassBody {
+  const strict = clamp(optics.legibility * 2, 0, 1);
+  const capLight = mix(BODY_CAP_LOOSE, BODY_CAP_TIGHT, strict);
+  const floorDark = 1 - capLight;
+  const pol = clamp(ink, 0, 1);
+  // With no ink on it, the model promises transparent glass: the requirement fades out with
+  // legibility rather than standing at a floor.
+  const demand = clamp(optics.legibility * 4, 0, 1);
+
+  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);
+
+  // 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
+  // light patch right beneath it, and the average knows nothing about that patch.
+  const edge = busy * BUSY_EDGE;
+  const inkHi = Math.min(mean + edge, 1);
+  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;
+
+  // 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 };
+}
+
+/**
+ * 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. The sign comes from the
+ * BACKDROP, not from ink polarity: lighter over dark, darker over light. It is a minimum, not an
+ * addition, so a body that is already dense enough is left alone.
+ */
+export function withPresence(body: GlassBody, optics: VireGlassOptics, sample: BodyBackdrop): GlassBody {
+  if (optics.presence <= 0) return body;
+  const mean = clamp(sample.luma, 0, 1);
+  const lighter = mean < 0.5;
+  const target = lighter ? Math.min(mean + optics.presence, 1) : Math.max(mean - optics.presence, 0);
+  const separation = Math.abs(target - mean);
+  const reached = Math.abs(body.tintLuma - mean) * body.density;
+  if (reached >= separation) return body;
+  const needed = separation / Math.max(Math.abs((lighter ? TINT_LIGHT : TINT_DARK) - mean), 1e-4);
+  return {
+    density: Math.max(body.density, Math.min(needed, MAX_DEMAND)),
+    tintLuma: lighter ? Math.max(body.tintLuma, mean) : Math.min(body.tintLuma, mean),
+  };
+}

package/src/dom/displacement.ts

@@ -0,0 +1,163 @@
+// The DOM renderer's own optics: an `feDisplacementMap` source built from the same causes as the
+// GL/AGSL shaders, so a page refracting live content still reads as the same material. See
+// `docs/superpowers/specs/2026-09-19-vireglass-over-live-dom.md` for the technique this encodes.
+import { bevelDp, thicknessDp, type VireGlassGeometry } from '../geometry';
+import { BEVEL } from '../law';
+import type { VireGlassOptics } from '../material';
+import {
+  sceneDistance,
+  sceneGradient,
+  touchWarp,
+  type MorphShape,
+  type TouchWarp,
+} from '../sdf';
+
+export type DisplacementMap = { url: string; width: number; height: number; scale: number };
+
+/** dp of rim displacement per dp of size-adjusted thickness, at full refraction strength (ior →
+ *  1.6). Tuned so the product default (V5: ior 1.5, thickness 28dp) lands well under `MAX_SCALE`
+ *  before it's ever clamped — the ceiling below is what actually limits denser glass. */
+const SCALE_GAIN = 0.75;
+
+/**
+ * `feDisplacementMap` displaces by `scale * (channel / 255 - 0.5)`: a full channel swing spans
+ * ±scale/2, and one 8-bit step is `scale/255` px — not `scale/127`, which an earlier version of
+ * this file assumed and which rendered every material at half its derived refraction.
+ *
+ * Measured in Chromium on 2026-09-19: at scale 40 (0.157 px/step) a high-contrast edge visibly
+ * terraces; at scale 12 (0.047 px/step) it does not. The ceiling sits between them and nearer
+ * the clean end — thick, high-index glass is flattened to it instead of its derived scale,
+ * trading rim depth for an edge without stairs.
+ */
+const MAX_STEP_PX = 0.09;
+const MAX_SCALE = 255 * MAX_STEP_PX;
+
+/**
+ * Samples across the bevel band, which is the only place the map carries anything. Everything
+ * inside it is a constant, and `feImage` stretches whatever it is given over the element anyway,
+ * so resolving the element is wasted work: a sheet at device resolution is 197 000 pixels of
+ * per-pixel maths and a PNG encode, 120 ms on attach and far past a frame during interaction.
+ *
+ * Eight samples describe a profile that is smooth by construction. The measured cost falls with
+ * the square of the reduction, and `check:dom` measures the displacement afterwards to say
+ * whether anything was lost.
+ */
+const BEVEL_SAMPLES = 8;
+
+/** Resolution the map is built at: enough to resolve the bevel, never more than the element. */
+function mapDensity(geometry: VireGlassGeometry, bevel: number, dpr: number): number {
+  if (bevel <= 0) return dpr;
+  return Math.min(dpr, BEVEL_SAMPLES / bevel);
+}
+
+/** True neutral is the unrepresentable 127.5; 128 is the nearest byte and leaves a residual
+ *  0.002 of the scale, far below one step and below a pixel at any usable scale. */
+function encode(displacement: number, scale: number): number {
+  const channel = Math.round(255 * (displacement / scale + 0.5));
+  return channel < 0 ? 0 : channel > 255 ? 255 : channel;
+}
+
+/** Mirrors the shader's `vgBevelSlope`, renormalized into 0..1: curvature concentrated at the
+ *  rim, the middle left flat. A plain linear ramp from `vgBevelT` alone reads as a chamfer, not a
+ *  lens — the same reason the shader doesn't use it raw either. */
+function bevelProfile(t: number): number {
+  const raw = Math.min(t / Math.sqrt(Math.max(1 - t * t * BEVEL.sphere, BEVEL.floor)), BEVEL.slopeMax);
+  return raw / BEVEL.slopeMax;
+}
+
+export type DisplacementState = {
+  /** Finger response (docs/reference.md §5): the field around the touch deforms, so the silhouette
+   *  the backdrop bends along deforms with it. */
+  touch?: TouchWarp;
+  /** Smooth-union neighbours (§5): shapes merging into one and splitting apart. */
+  smoothing?: number;
+  morph?: MorphShape;
+  morph2?: MorphShape;
+};
+
+/**
+ * The raw pixel buffer, with no canvas involved — the part actually worth unit-testing.
+ * `buildDisplacementMap` below is a thin DOM wrapper around this.
+ *
+ * Encoding: R = x offset, G = y offset, 128 = no shift, one step = `scale/255` px; B = 128
+ * (unused), A = 255 (opaque, `feImage` would otherwise composite the map against page black).
+ * The offset points INWARD — the rim samples the backdrop from inside the shape, a convex thick
+ * lens. Displacement lives only in the bevel band (`bevelDp`); the flat middle is exactly 128/128.
+ */
+export function renderDisplacementPixels(
+  optics: VireGlassOptics,
+  geometry: VireGlassGeometry,
+  dpr: number,
+  state: DisplacementState = {},
+): { data: Uint8ClampedArray; width: number; height: number; scale: number } {
+  const bevel = bevelDp(geometry, optics);
+  const density = mapDensity(geometry, bevel, dpr);
+  const width = Math.max(1, Math.round(geometry.width * density));
+  const height = Math.max(1, Math.round(geometry.height * density));
+  const rawScale = optics.refraction * thicknessDp(geometry, optics) * SCALE_GAIN;
+  const scale = Math.min(rawScale, MAX_SCALE);
+  const smoothing = state.smoothing ?? 0;
+
+  const data = new Uint8ClampedArray(width * height * 4);
+  const halfW = geometry.width / 2;
+  const halfH = geometry.height / 2;
+
+  for (let py = 0; py < height; py += 1) {
+    const y = (py + 0.5) / density - halfH;
+    for (let px = 0; px < width; px += 1) {
+      const x = (px + 0.5) / density - halfW;
+      const i = (py * width + px) * 4;
+      // Warp the FIELD first, then read the scene at the warped point — the shader's own order.
+      const [wx, wy] = state.touch ? touchWarp(x, y, state.touch) : [x, y];
+      const sd = sceneDistance(wx, wy, geometry.width, geometry.height, geometry.cornerRadius, smoothing, state.morph, state.morph2);
+      const t = Math.min(Math.max((sd + bevel) / bevel, 0), 1);
+      if (t <= 0 || scale <= 0) {
+        data[i] = 128;
+        data[i + 1] = 128;
+        data[i + 2] = 128;
+        data[i + 3] = 255;
+        continue;
+      }
+      const [gx, gy] = sceneGradient(wx, wy, geometry.width, geometry.height, geometry.cornerRadius, smoothing, state.morph, state.morph2);
+      // The rim reaches half the scale: the encoding can only span ±scale/2, so the derived
+      // displacement is expressed as a fraction of that half-range.
+      const magnitude = bevelProfile(t) * (scale / 2);
+      const dx = -gx * magnitude;
+      const dy = -gy * magnitude;
+      // Inverse of the spec's own formula: channel = 255 * (displacement / scale + 0.5).
+      data[i] = encode(dx, scale);
+      data[i + 1] = encode(dy, scale);
+      data[i + 2] = 128;
+      data[i + 3] = 255;
+    }
+  }
+
+  return { data, width, height, scale };
+}
+
+function hasCanvasSupport(): boolean {
+  return typeof document !== 'undefined' && typeof document.createElement === 'function';
+}
+
+/** Builds the map at device-pixel resolution so it stays sharp once the browser stretches it back
+ *  over the element's CSS-px box (`feImage` fills the filter region regardless of source size). */
+export function buildDisplacementMap(
+  optics: VireGlassOptics,
+  geometry: VireGlassGeometry,
+  dpr: number,
+  state: DisplacementState = {},
+): DisplacementMap {
+  if (!hasCanvasSupport()) {
+    throw new Error('vireglass/dom: buildDisplacementMap requires a DOM (canvas)');
+  }
+  const { data, width, height, scale } = renderDisplacementPixels(optics, geometry, dpr, state);
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) throw new Error('vireglass/dom: 2D canvas context unavailable');
+  const imageData = ctx.createImageData(width, height);
+  imageData.data.set(data);
+  ctx.putImageData(imageData, 0, 0);
+  return { url: canvas.toDataURL('image/png'), width, height, scale };
+}

package/src/dom/group.ts

@@ -0,0 +1,124 @@
+// A row of glass that agrees with itself.
+//
+// Each element probing on its own is not merely wasteful — it is wrong. Neighbouring pieces of one
+// control sit over slightly different patches of backdrop, reach different polarities, and a tab
+// bar ends up with two light glyphs and two dark ones. §3 is explicit that small elements switch
+// WHOLESALE; a group is what "wholesale" means when the element is really four of them.
+//
+// Every decision is the core's (`../group-model`): the lightness plane, the smoothing, the polarity
+// requirement and its hysteresis. This binds them to real elements.
+import { createGroupState, type GroupPlane } from '../group-model';
+import { TOUCH } from '../law';
+import { probeBackdrop } from './probe';
+import type { BackdropSample } from '../adaptation';
+import type { GlassHandle } from './index';
+
+export type GroupEntry = {
+  el: HTMLElement;
+  handle: GlassHandle;
+  /** Set by the group: pass it to this member's own `attachGlass` as `onGlow`. */
+  onGlow?: (glow: { pageX: number; pageY: number; strength: number } | null) => void;
+  /** How strongly this member needs its ink to stay legible. The strictest in the group wins. */
+  legibility?: number;
+};
+
+export type GlassGroupHandle = {
+  /** Re-read every member and settle on one answer for all of them. */
+  update(): void;
+  /** The polarity the whole group agreed on, 1 light and 0 dark. */
+  ink(): number;
+  /** The group's current estimate, or null before the first reading. */
+  plane(): GroupPlane | null;
+  /** Spread a glow from one member to the rest. Members wired through `onGlow` call this for you. */
+  carryGlow(from: number, glow: { pageX: number; pageY: number; strength: number } | null): void;
+  destroy(): void;
+};
+
+export type GlassGroupOptions = {
+  /** Where a member reads its backdrop. Defaults to the DOM probe. */
+  probe?: (el: HTMLElement) => BackdropSample;
+};
+
+export function createGlassGroup(
+  members: readonly GroupEntry[],
+  opts: GlassGroupOptions = {},
+): GlassGroupHandle {
+  let polarity = 1;
+  let destroyed = false;
+
+  const state = createGroupState({
+    plane: () => {},
+    flip: (next) => {
+      polarity = next;
+      // One flip, everyone at once — that is the whole point of the group.
+      for (const { handle } of members) handle.update();
+    },
+  });
+
+  /**
+   * "Starting right under your fingertips, the glow spreads throughout the element and onto any
+   * Liquid Glass elements nearby" (§5, 219 @12:11). The element being touched cannot know who is
+   * nearby; the group does.
+   */
+  function carryGlow(from: number, glow: { pageX: number; pageY: number; strength: number } | null): void {
+    members.forEach(({ el, handle }, index) => {
+      if (index === from) return;
+      if (!glow) {
+        handle.setNeighbourGlow(null);
+        return;
+      }
+      const rect = el.getBoundingClientRect();
+      const cx = rect.left + rect.width / 2;
+      const cy = rect.top + rect.height / 2;
+      const reach = (Math.min(rect.width, rect.height) / 2) * TOUCH.glowReach;
+      const distance = Math.hypot(glow.pageX - cx, glow.pageY - cy);
+      // Falls off with distance and stops: a glow that reached the whole screen would read as the
+      // page flashing rather than as light travelling through neighbouring glass.
+      const falloff = reach > 0 ? Math.max(0, 1 - distance / reach) : 0;
+      handle.setNeighbourGlow(falloff <= 0 ? null : { ...glow, strength: glow.strength * falloff });
+    });
+  }
+
+  /** Wire each member's own touch to the rest of the group. */
+  function connect(): void {
+    members.forEach((entry, index) => {
+      entry.onGlow = (glow) => carryGlow(index, glow);
+    });
+  }
+
+  function update(): void {
+    if (destroyed) return;
+    const probe = opts.probe ?? probeBackdrop;
+    members.forEach(({ el, legibility }, index) => {
+      const rect = el.getBoundingClientRect();
+      // A member with no box has nothing behind it to read; reporting it anyway would drag the
+      // group's estimate toward whatever sits at the page's origin.
+      if (rect.width <= 0 || rect.height <= 0) {
+        state.release(String(index));
+        return;
+      }
+      state.report(
+        String(index),
+        rect.left + rect.width / 2,
+        rect.top + rect.height / 2,
+        probe(el),
+        legibility ?? 0,
+      );
+    });
+  }
+
+  connect();
+  update();
+
+  return {
+    update,
+    ink: () => polarity,
+    plane: () => state.plane(),
+    carryGlow,
+    destroy() {
+      destroyed = true;
+      carryGlow(-1, null);
+      members.forEach((_, index) => state.release(String(index)));
+    },
+  };
+}