vireglass 0.1.0

package/src/reference-scene.ts

@@ -0,0 +1,222 @@
+/**
+ * REFERENCE CANVASES — the set that both benches draw and that the gates run against.
+ *
+ * There used to be three kinds of canvas, each in a different place: the web bench had its own
+ * zones, the mobile lab had its own, and a third set lived inside `check-optics.mjs`, invisible
+ * to everyone else. So the gate measured one thing, the eye looked at another, and there was
+ * nothing to confirm the question "does Android differ?" against.
+ *
+ * The canvases are described as DATA, not drawing code: the canvas and the native views draw
+ * differently, but both platforms lay out the same list of layers. Everything is in dp and in
+ * fractions — fractions of the stage kept the stripes the same relative thickness on benches of
+ * different sizes.
+ *
+ * Each canvas answers for one promise of the material (`what`), and that's also the caption on
+ * the bench. A canvas can't be added to only one bench: platform parity would go back to being
+ * a matter of impression.
+ */
+
+import { capsuleGeometry, circleGeometry, roundedRectGeometry, type VireGlassGeometry } from './geometry';
+
+/**
+ * BENCH SHAPES — shared too. Element size feeds into the optics through sizeGain: a 120 circle
+ * and a 150 circle are glass of different thickness, and screenshots from two benches on
+ * different shapes are as incomparable as on different canvases. The values match the ones the
+ * reference comparisons were shot on.
+ */
+export const REFERENCE_SHAPES = {
+  circle: circleGeometry(120),
+  capsule: capsuleGeometry(300, 110),
+  tile: roundedRectGeometry(220, 120, 32),
+} satisfies Record<string, VireGlassGeometry>;
+
+export type VireGlassRefShapeName = keyof typeof REFERENCE_SHAPES;
+
+/** A stripe's layer. Lightness is 0..1, sizes are dp: gray, not color (there's nothing to
+ *  measure color with). */
+export type VireGlassRefLayer =
+  | { readonly kind: 'flat'; readonly level: number }
+  /** Vertical stripes: wider than the bevel, so the body absorbs them rather than the rim. */
+  | { readonly kind: 'stripes'; readonly level: number; readonly other: number; readonly periodDp: number; readonly widthDp: number }
+  /** A pseudo-random checkerboard — a "cover": structure that fights the ink drawn over the glass. */
+  | { readonly kind: 'checker'; readonly level: number; readonly amp: number; readonly cellDp: number }
+  /** Left and right halves at different lightness. */
+  | { readonly kind: 'step'; readonly left: number; readonly right: number }
+  /** A dark bar across the middle of the stripe — measures bulging at the rim against it. */
+  | { readonly kind: 'bar'; readonly level: number; readonly barLevel: number; readonly thicknessDp: number }
+  /** A fine grid: any lens distortion shows up on a straight line right away. */
+  | { readonly kind: 'grid'; readonly level: number; readonly lineLevel: number; readonly stepDp: number }
+  /** A stepped gradient. Steps, not a smooth fill: the native views can't draw a gradient without
+   *  an image. */
+  | { readonly kind: 'gradient'; readonly from: number; readonly to: number; readonly steps: number };
+
+export type VireGlassRefBand = {
+  /** Stripe thickness in dp. The sum over a canvas is `REFERENCE_SCENE_HEIGHT`. */
+  readonly heightDp: number;
+  readonly layer: VireGlassRefLayer;
+};
+
+/**
+ * Canvas size IN DP, one for all. Height is kept within the mobile lab's zone (0.42 of the
+ * screen height), width within the narrowest phone (360 dp) with room to spare for the
+ * surrounding field.
+ *
+ * Width matters NO LESS than height. The pattern is measured from the edge of the canvas, so on
+ * a canvas spanning the full width of the stage, the phase of the pattern under the element
+ * depended on screen width: 24 dp-period stripes landed under the center differently on a 406 dp
+ * phone versus a fifteen-hundred-pixel canvas, and the checkerboard put an entirely different
+ * cell arrangement under the element. A fixed-size panel removes this whole class of discrepancy
+ * at once.
+ */
+export const REFERENCE_SCENE_WIDTH = 336;
+export const REFERENCE_SCENE_HEIGHT = 252;
+
+/** The field around the canvas. Deliberately off the stripe levels and not gray: it shows where
+ *  the reference area ends, so its border can't be mistaken for a stripe in a screenshot. */
+export const REFERENCE_SURROUND = '#3c1f4a';
+
+/**
+ * Where the element sits on the canvas — dp from the panel's top-left corner. Position is as much
+ * a part of the contract as canvas size and shape: a bench that parks the element its own way
+ * shows it over DIFFERENT stripes, and there's nothing left to compare screenshots against.
+ *
+ * This has drifted before: the web bench centered the element within the VISIBLE area, while the
+ * canvas was drawn centered on the full canvas element — with the control panel open, those are
+ * two different points.
+ */
+export const REFERENCE_PIECE_AT = {
+  xDp: REFERENCE_SCENE_WIDTH / 2,
+  yDp: REFERENCE_SCENE_HEIGHT / 2,
+} as const;
+
+export type VireGlassRefScene = {
+  readonly name: string;
+  /** What this canvas checks. Also the caption on the bench — otherwise the set turns to mush. */
+  readonly what: string;
+  /** Stripes at a given backdrop lightness: benches call with `level`, the gate sweeps the whole range. */
+  readonly bands: (level: number) => readonly VireGlassRefBand[];
+  /** Default lightness. Canvases that don't need it simply ignore it. */
+  readonly level: number;
+  /**
+   * Whether the canvas is fit for NUMERIC platform comparison. A lightness profile needs a
+   * backdrop that's uniform along the row; on a periodic grid of pixel-wide lines, the average
+   * is determined by how the platform rasterizes that line, not by the material. Such a canvas
+   * stays in the set — distortion of a straight line is visible to the eye at a glance — but it's
+   * excluded from the comparison table.
+   */
+  readonly measurable?: false;
+};
+
+const whole = (layer: VireGlassRefLayer): readonly VireGlassRefBand[] => [
+  { heightDp: REFERENCE_SCENE_HEIGHT, layer },
+];
+
+/** Stripe contrast is the same at every level, so transmission compares fairly between steps. */
+const stripeLevel = (level: number) => (level < 0.5 ? level + 0.22 : level - 0.22);
+
+export const REFERENCE_SCENES: readonly VireGlassRefScene[] = [
+  {
+    name: 'flat',
+    what: 'the body standing off the backdrop: the element must be visible over a flat canvas',
+    level: 0.5,
+    bands: (level) => whole({ kind: 'flat', level }),
+  },
+  {
+    name: 'stripes',
+    what: 'the window: the brightness range inside the element is a noticeable fraction of the range outside it',
+    level: 0.5,
+    bands: (level) => whole({ kind: 'stripes', level, other: stripeLevel(level), periodDp: 24, widthDp: 10 }),
+  },
+  {
+    name: 'busy',
+    what: 'ink against content: both the ink and whatever is under the glass have to live over a busy cover',
+    level: 0.5,
+    bands: (level) => whole({ kind: 'checker', level, amp: 0.28, cellDp: 16 }),
+  },
+  {
+    name: 'bar',
+    what: 'the rim gathers content: at the silhouette the lens bulges out whatever sits behind it',
+    level: 0.93,
+    bands: (level) => whole({ kind: 'bar', level, barLevel: 0.12, thicknessDp: 20 }),
+  },
+  {
+    name: 'steps',
+    what: 'the body profile at five levels at once — platforms are compared against it',
+    level: 0.5,
+    bands: () => [
+      { heightDp: 36, layer: { kind: 'flat', level: 0.1 } },
+      { heightDp: 36, layer: { kind: 'flat', level: 0.3 } },
+      { heightDp: 36, layer: { kind: 'flat', level: 0.5 } },
+      { heightDp: 36, layer: { kind: 'flat', level: 0.69 } },
+      { heightDp: 36, layer: { kind: 'flat', level: 0.9 } },
+      { heightDp: 36, layer: { kind: 'step', left: 0.05, right: 0.28 } },
+      { heightDp: 36, layer: { kind: 'bar', level: 0.92, barLevel: 0.12, thicknessDp: 6 } },
+    ],
+  },
+  {
+    name: 'edge',
+    what: 'tint at a hard break: one half under the glass is black, the other white',
+    level: 0.5,
+    bands: () => whole({ kind: 'step', left: 0.03, right: 0.95 }),
+  },
+  {
+    name: 'gradient',
+    what: 'ink polarity: where the automatic switch flips the ink from light to dark',
+    level: 0.5,
+    bands: () => whole({ kind: 'gradient', from: 0.04, to: 0.96, steps: 28 }),
+  },
+  {
+    name: 'grid',
+    what: 'lens distortion: drift, tearing and jitter of a straight line show up immediately (by eye, not by number)',
+    level: 0.91,
+    measurable: false,
+    bands: (level) => whole({ kind: 'grid', level, lineLevel: level > 0.5 ? level - 0.14 : level + 0.14, stepDp: 12 }),
+  },
+];
+
+export type VireGlassRefSceneName = (typeof REFERENCE_SCENES)[number]['name'];
+
+export const referenceScene = (name: string): VireGlassRefScene => {
+  const scene = REFERENCE_SCENES.find((s) => s.name === name);
+  if (!scene) throw new Error(`vireglass: no reference canvas "${name}"`);
+  return scene;
+};
+
+/** Lightness to hex gray. One conversion for both platforms — otherwise they'd drift apart. */
+export const refGray = (level: number): string => {
+  const v = Math.round(Math.min(Math.max(level, 0), 1) * 255)
+    .toString(16)
+    .padStart(2, '0');
+  return `#${v}${v}${v}`;
+};
+
+/**
+ * Checkerboard cells as POSITIONS, not as drawing: the canvas loops over them, the native views
+ * lay them out as a list, and both platforms get the exact same arrangement. The generator is
+ * its own and deliberately simple — `Math.random` would give two platforms different canvases.
+ */
+export const refCheckerCells = (
+  layer: Extract<VireGlassRefLayer, { kind: 'checker' }>,
+  widthDp: number,
+  heightDp: number,
+): readonly { readonly xDp: number; readonly yDp: number; readonly level: number }[] => {
+  const cells: { xDp: number; yDp: number; level: number }[] = [];
+  const lo = layer.level - layer.amp;
+  const hi = layer.level + layer.amp;
+  let seed = 1;
+  for (let y = 0; y < heightDp; y += layer.cellDp) {
+    for (let x = 0; x < widthDp; x += layer.cellDp) {
+      seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+      cells.push({ xDp: x, yDp: y, level: (seed >> 16) % 2 ? hi : lo });
+    }
+  }
+  return cells;
+};
+
+/** Gradient steps — also positions: the same list for the canvas and for the native views. */
+export const refGradientSteps = (
+  layer: Extract<VireGlassRefLayer, { kind: 'gradient' }>,
+): readonly number[] =>
+  Array.from({ length: layer.steps }, (_, i) =>
+    layer.from + ((layer.to - layer.from) * i) / Math.max(layer.steps - 1, 1),
+  );

package/src/scroll-edge.ts

@@ -0,0 +1,30 @@
+// Scroll edge effect (reference 219 @8:52) — the SCREEN's job, not the material's: it sits over
+// the content beneath the panel, and the glass sees an already-dimmed backdrop. Only the general
+// rules live here.
+
+export type ScrollEdgeStyle = 'dissolve' | 'dim' | 'hard';
+
+/**
+ * The edge style follows the style of the nearest glass: light ink means dark glass, and the
+ * content beneath it fades into a light dimming; dark ink means light glass, and the content
+ * dissolves into the background. A pinned view under the panel (column headers) gets a flat
+ * band with no gradient.
+ */
+export function scrollEdgeStyle(inkLight: boolean, pinned = false): ScrollEdgeStyle {
+  if (pinned) return 'hard';
+  return inkLight ? 'dim' : 'dissolve';
+}
+
+/** How far the content has to slide under the panel for the effect to fully engage, dp. */
+export const SCROLL_EDGE_ENGAGE_DP = 24;
+
+/**
+ * Edge strength as a function of scroll. With no scroll, content near the top doesn't slide
+ * under the panel yet — so there's no effect (a mail screen at the top: the header sits on a
+ * clean background). At the bottom, content slides under it for as long as there's room left
+ * to scroll.
+ */
+export function scrollEdgeStrength(side: 'top' | 'bottom', scroll: number, maxScroll: number): number {
+  const room = side === 'top' ? scroll : maxScroll - scroll;
+  return Math.min(Math.max(room / SCROLL_EDGE_ENGAGE_DP, 0), 1);
+}

package/src/sdf.ts

@@ -0,0 +1,149 @@
+// The single description of VireGlass geometry. Both shaders draw it from here: the SKSL surface
+// (`surface-shader.ts`) and the AGSL lens (`lens-shader.ts`, shipped as a string into the native
+// view). AGSL and SKSL are the same language, so the SDF no longer needs duplicating in Kotlin:
+// before, the surface's circle and the lens's rounded rectangle described different pieces of
+// glass, and the bevel constant had to be kept in sync by hand (docs/adr-001-rendering.md §3).
+export const VG_SDF = `
+float vgRoundRect(float2 p, float2 halfSize, float corner) {
+  float2 q = abs(p) - halfSize + corner;
+  return min(max(q.x, q.y), 0.0) + length(max(q, float2(0.0))) - corner;
+}
+
+float vgSmin(float a, float b, float k) {
+  float h = clamp(0.5 + 0.5 * (b - a) / k, 0.0, 1.0);
+  return mix(b, a, h) - k * h * (1.0 - h);
+}
+
+// A scene is a single shape, and when k > 0 a smooth union with one or two neighbors. A third
+// shape exists to break the control into pieces (docs/reference.md §5): there are two bridges
+// there. It's turned off with a zero size, not its own k: the fused body shares one bridge.
+float vgScene(float2 p, float2 halfSize, float corner,
+              float2 offsetB, float2 halfB, float cornerB, float k,
+              float2 offsetC, float2 halfC, float cornerC) {
+  float a = vgRoundRect(p, halfSize, corner);
+  if (k <= 0.0) { return a; }
+  float ab = vgSmin(a, vgRoundRect(p - offsetB, halfB, cornerB), k);
+  if (halfC.x <= 0.0) { return ab; }
+  return vgSmin(ab, vgRoundRect(p - offsetC, halfC, cornerC), k);
+}
+
+// Response to a finger. It's the FIELD around the touch point that deforms, not the shape's
+// bounding box: scaling width to pull the right edge would also pull the left one — liquid
+// doesn't behave that way. Here the displacement falls off with distance from the finger, so the
+// far edge stays put.
+//
+// The order of the terms matters: drag shifts the field, press pulls it toward the finger, the
+// wave rides on top of the already-shifted field — otherwise the ripple decouples from the
+// deformation and lives a life of its own.
+float2 vgTouchWarp(float2 p, float2 touch, float2 pull, float press, float radius,
+                   float waveAmp, float wavePhase) {
+  if (radius <= 0.0) { return p; }
+  // Under the finger the whole element grows (M 3:51; HIG: interactive "expands").
+  p /= 1.0 + 0.06 * press;
+  float2 d = p - touch;
+  float r = length(d);
+
+  // The finger is a BLOB, not a point, but not a hard stamp either: a wide peak, soft edges. A
+  // flat plateau with a sharp cutoff at the edge shifts the region as a block, and a straight
+  // line under the glass breaks into a step — the deformation reads as rectangular even though
+  // the finger is round. A double smoothstep gives the same contact width without that step.
+  //
+  // The influence cuts off at the radius rather than fading into an infinite tail like a
+  // Gaussian: with a tail the deformation spreads into a "rubber mattress" bulge.
+  float k = clamp((radius - r) / radius, 0.0, 1.0);
+  float s = k * k * (3.0 - 2.0 * k);
+  float core = s * s * (3.0 - 2.0 * s);
+  // A ring around the blob: material displaced from under the finger has to end up somewhere.
+  // Without this ridge the shape just balloons, and a dense medium doesn't behave that way.
+  float rim = k * k * (1.0 - k) * 4.0;
+
+  float2 q = p - pull * (core - 0.42 * rim);
+  q -= d * (press * 0.16 * core);
+
+  // The wave has its own scale, twice the drag radius: the ripple has to reach the far edge,
+  // otherwise it reads as jitter under the finger rather than a wave across the surface. The
+  // wavelength is short: in a dense medium ripples are frequent and small, long shallow swells
+  // are water.
+  if (waveAmp > 0.0 && r > 0.0001) {
+    float span = radius * 2.0;
+    float ring = sin(r / (span * 0.17) - wavePhase * 6.2831853) * exp(-r / (span * 0.7));
+    q -= (d / r) * ring * waveAmp;
+  }
+  return q;
+}
+
+// Analytical normal of a single shape: radial on the rounded part, axis-aligned on the straight
+// segments.
+float2 vgRoundRectNormal(float2 p, float2 halfSize, float corner) {
+  float2 q = abs(p) - halfSize + corner;
+  float2 g = (q.x > 0.0 && q.y > 0.0)
+    ? normalize(max(q, float2(0.0001)))
+    : (q.x > q.y ? float2(1.0, 0.0) : float2(0.0, 1.0));
+  return g * sign(p);
+}
+
+// Normal of the union — ANALYTICAL, no more finite differences here.
+//
+// Derivation: smin has two terms, mix(b,a,h) and −k·h·(1−h). Their derivatives with respect to h
+// contain a factor of (1−2h) with opposite signs and cancel exactly, because h is linear in
+// (b−a)/k. What's left is mix(∇b, ∇a, h) — that is, the two shapes' normals, blended with the
+// same weight that blends the distances themselves.
+//
+// The previous version took four ADDITIONAL scene evaluations per pixel (each one — two shapes
+// plus smin) and was still an approximation. Here there are two shapes, exactly.
+float2 vgSceneNormal(float2 p, float2 halfSize, float corner,
+                     float2 offsetB, float2 halfB, float cornerB, float k,
+                     float2 offsetC, float2 halfC, float cornerC) {
+  float2 na = vgRoundRectNormal(p, halfSize, corner);
+  if (k <= 0.0) { return na; }
+  float2 q = p - offsetB;
+  float a = vgRoundRect(p, halfSize, corner);
+  float b = vgRoundRect(q, halfB, cornerB);
+  float h = clamp(0.5 + 0.5 * (b - a) / k, 0.0, 1.0);
+  float2 nab = normalize(mix(vgRoundRectNormal(q, halfB, cornerB), na, h) + float2(1e-5, 1e-5));
+  if (halfC.x <= 0.0) { return nab; }
+  // Same derivation as for the pair: normals blend with the same weight as the distances.
+  float2 qc = p - offsetC;
+  float ab = vgSmin(a, b, k);
+  float c = vgRoundRect(qc, halfC, cornerC);
+  float hc = clamp(0.5 + 0.5 * (c - ab) / k, 0.0, 1.0);
+  return normalize(mix(vgRoundRectNormal(qc, halfC, cornerC), nab, hc) + float2(1e-5, 1e-5));
+}
+
+// Position within the bevel: 0 is the flat middle, 1 is the very edge. This one value feeds the
+// mask, thickness, refraction, aberrations and the width of the light rim.
+float vgBevelT(float sd, float bevel) {
+  return clamp((sd + bevel) / bevel, 0.0, 1.0);
+}
+
+// Slope of the bevel profile — spherical: t / sqrt(1 - t²), like a spherical cap. The previous t²
+// kept the slope near zero through almost the whole bevel and then shot up right at the edge, so
+// all the optics bunched into a narrow ring and the element read as a PUCK — a flat top and a
+// wall around the rim. Here curvature is spread across the bevel, and the rim stops being a line.
+//
+// This still doesn't control the field of view: only the bevel bends, the middle stays flat,
+// otherwise the surface reads as a soap bubble.
+float vgBevelSlope(float t) {
+  return min(t * inversesqrt(max(1.0 - t * t * 0.94, 0.02)), 3.2);
+}
+
+// PROGRESS FRACTION. Progress is an active state turned into a FIELD: to the left of the boundary
+// the element is active, to the right it stays regular glass, and the boundary moves. A negative
+// value turns the field off entirely — zero is taken by the start of the track and can't also
+// mean off.
+//
+// The boundary is SOFT. A hard seam reads as two different materials glued together rather than
+// two states of one; the transition width is a fraction of the half-width, so it doesn't read as
+// a thread on a large element and doesn't swallow a small one whole.
+float vgProgress(float2 p, float2 halfSize, float progress) {
+  if (progress < 0.0) { return 0.0; }
+  float edge = mix(-halfSize.x, halfSize.x, clamp(progress, 0.0, 1.0));
+  float soft = max(halfSize.x * 0.05, 1.0);
+  return 1.0 - smoothstep(edge - soft, edge + soft, p.x);
+}
+`;
+
+/** Rate at which the offset builds toward the rim. Shared between the lens (actual sampling
+ *  offset) and the surface (visualizing the displacement field in debug mode) — otherwise they'd
+ *  drift apart. */
+export const VG_FALLOFF = 2.6;