@dopaminefx/core 0.1.0

package/src/engine/look/glsl.ts

@@ -0,0 +1,183 @@
+/**
+ * Shared GLSL "look" chunk library.
+ *
+ * The three effects grew in parallel and each re-implemented (and drifted) the
+ * same building blocks inside its own shader: value-noise + fbm + domain warp,
+ * the palette mix, the segment SDF, the ACES tonemap, the IQ-cosine iridescence,
+ * the Ben-Day halftone and the ordered dither. Per the cross-pollination plan,
+ * those are lifted here into ONE canonical copy each, so every shader composes
+ * the SAME function instead of a private fork. Effects assemble their fragment
+ * source by concatenating the chunks they need ahead of their own `main()`.
+ *
+ * Each chunk is a self-contained GLSL snippet (no `#version`/`precision`/IO —
+ * those stay in the per-effect shader). The text below is byte-identical to the
+ * canonical implementations the effects already shipped, so adopting the library
+ * does not change any effect's look; it only removes the duplication + drift.
+ *
+ * NOTE: This is a GLSL *chunk* library (string includes), not a transpiler — it
+ * maps onto the `.dope` format's referenced shader bodies (the format references
+ * GLSL; it does not generate it).
+ */
+
+/** TAU + a couple of constants every effect uses. */
+export const GLSL_CONSTANTS = /* glsl */ `
+#define TAU 6.28318530718
+`;
+
+/**
+ * Hash helpers (Dave Hoskins style) — `hash11` (1→1) and `hash21` (1→2). Used
+ * by the noise field, the particles, and the per-frame dither.
+ */
+export const GLSL_HASH = /* glsl */ `
+float hash11(float p){ p = fract(p * 0.1031); p *= p + 33.33; p *= p + p; return fract(p); }
+vec2 hash21(float p){
+  vec3 p3 = fract(vec3(p) * vec3(0.1031, 0.1030, 0.0973));
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.xx + p3.yz) * p3.zy);
+}
+`;
+
+/**
+ * Value noise + 4-octave fbm with a per-octave rotation (kills axis-aligned
+ * artifacts). Requires GLSL_HASH. This is the volumetric texture source for the
+ * bloom interior and the wet-ink edge wobble.
+ */
+export const GLSL_FBM = /* glsl */ `
+float vnoise(vec2 p){
+  vec2 i = floor(p), f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = hash11(dot(i, vec2(1.0, 57.0)));
+  float b = hash11(dot(i + vec2(1.0, 0.0), vec2(1.0, 57.0)));
+  float c = hash11(dot(i + vec2(0.0, 1.0), vec2(1.0, 57.0)));
+  float d = hash11(dot(i + vec2(1.0, 1.0), vec2(1.0, 57.0)));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+float fbm(vec2 p){
+  float s = 0.0, a = 0.5;
+  mat2 rot = mat2(0.80, -0.60, 0.60, 0.80);
+  for (int i = 0; i < 4; i++) { s += a * vnoise(p); p = rot * p * 2.03; a *= 0.5; }
+  return s;
+}
+`;
+
+/**
+ * Two-level domain warp: warp the sample point by an fbm-derived offset, then
+ * sample fbm again — the smoke-like living interior of a real bloom. Returns the
+ * warped fbm value at `p`; `t` is time, `amount` the warp strength. Requires
+ * GLSL_FBM.
+ */
+export const GLSL_DOMAIN_WARP = /* glsl */ `
+float domainWarp(vec2 p, float t, float amount){
+  vec2 warp = vec2(fbm(p + t * 0.18), fbm(p.yx - t * 0.12)) - 0.5;
+  return fbm(p + warp * 1.2 * amount + t * 0.25);
+}
+`;
+
+/** 3-stop palette mix (inner→mid→outer). Effects declare uC0/uC1/uC2 uniforms. */
+export const GLSL_PALETTE_MIX = /* glsl */ `
+vec3 paletteMix(float t){
+  t = clamp(t, 0.0, 1.0);
+  return t < 0.5 ? mix(uC0, uC1, t * 2.0) : mix(uC1, uC2, (t - 0.5) * 2.0);
+}
+`;
+
+/**
+ * Inigo Quilez cosine palette — a smooth spectral sweep used for thin-film
+ * iridescence (oil-on-water sheen): cycles through complementary hues, NOT the
+ * mood palette, so it reads as an iridescent film over the mark.
+ */
+export const GLSL_IRIDESCENT = /* glsl */ `
+vec3 iridescent(float t){
+  return 0.55 + 0.45 * cos(TAU * (vec3(1.0) * t + vec3(0.0, 0.33, 0.67)));
+}
+`;
+
+/**
+ * Spectral dispersion amount at a refractive edge — grows toward the rim and
+ * with amplitude, gated by a 0..1 strength. `dn` is normalized radius/edge
+ * proximity (1 == edge); used to sample a profile at channel-shifted positions.
+ */
+export const GLSL_DISPERSION = /* glsl */ `
+float dispersionAmount(float strength, float dn, float amp){
+  return strength * (0.06 + 0.12 * smoothstep(0.2, 1.1, dn)) * (0.7 + 0.5 * amp);
+}
+`;
+
+/** Capsule/segment SDF (the safe variant — guards zero-length segments). */
+export const GLSL_SD_SEG = /* glsl */ `
+float sdSeg(vec2 p, vec2 a, vec2 b){
+  vec2 pa = p - a, ba = b - a;
+  float h = clamp(dot(pa, ba) / max(dot(ba, ba), 1e-3), 0.0, 1.0);
+  return length(pa - ba * h);
+}
+`;
+
+/**
+ * ACES filmic tonemap (Narkowicz) — richer highlight rolloff than `x/(1+x)`,
+ * keeps highlights from going chalky while preserving saturated mid-lights.
+ */
+export const GLSL_TONEMAP_ACES = /* glsl */ `
+vec3 tonemapACES(vec3 x){
+  const float a = 2.51, b = 0.03, c = 2.43, d = 0.59, e = 0.14;
+  return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0);
+}
+`;
+
+/**
+ * Ordered/triangular-hash dither, ~1/255, to break the smooth-gradient banding
+ * the screen blend reveals on the page beneath. `frag` device px, `t` seconds,
+ * `fade` 0..1 (1 = full dither; effects fade it out toward the cel/pop end where
+ * hard bands are intended). Requires GLSL_HASH.
+ */
+export const GLSL_DITHER = /* glsl */ `
+vec3 ditherAdd(vec3 col, vec2 frag, float t, float fade){
+  float dz = hash11(dot(frag, vec2(12.989, 78.233)) + t) - 0.5;
+  return col + (dz / 255.0) * fade;
+}
+`;
+
+/**
+ * Ben-Day halftone coverage: 1 inside a dot, 0 outside, antialiased. Dot RADIUS
+ * grows with tone `v`; the screen is rotated by `ang` (classic per-channel
+ * screen angle). Requires the matrix helper below.
+ */
+export const GLSL_ROT2 = /* glsl */ `
+mat2 rot2(float a){ float s = sin(a), c = cos(a); return mat2(c, -s, s, c); }
+`;
+
+export const GLSL_HALFTONE = /* glsl */ `
+float benday(vec2 frag, float cell, float v, float ang){
+  vec2 p = rot2(ang) * frag / cell;
+  vec2 g = fract(p) - 0.5;
+  float d = length(g);
+  float r = 0.52 * sqrt(clamp(v, 0.0, 1.0));
+  float aa = 0.7 / cell + fwidth(d);
+  return 1.0 - smoothstep(r - aa, r + aa, d);
+}
+`;
+
+/**
+ * PREMULTIPLIED LIGHT OUT — the portable compositing emit.
+ *
+ * The default web overlay leans on CSS `mix-blend-mode: screen` to cast the
+ * effect's light onto the page, which is rich on a dark UI but mathematically
+ * invisible on white (`screen(x, 1) == 1`). The native stacks (iOS/Android) have
+ * no per-surface screen blend, so they instead emit PREMULTIPLIED light — `rgb`
+ * unchanged, `alpha = its own brightness` — and let the OS composite it
+ * source-over: dark regions go transparent (the host shows through), bright
+ * light reads as cast colour, and crucially it stays visible on ANY backdrop,
+ * white included. This is byte-identical to Android's `Look.kt` `dopLightOut`.
+ *
+ * The web runtime reuses this for its "backdrop"-aware compositing path: when a
+ * caller passes a known surface colour, the light pass swaps its opaque
+ * `vec4(col, 1.0)` emit for `dopLightOut(col)` and composites source-over
+ * (`mix-blend-mode: normal`) instead of screen — see `pass-common.ts`'s
+ * `compositeLightFragment`.
+ */
+export const GLSL_LIGHT_OUT = /* glsl */ `
+vec4 dopLightOut(vec3 col){
+  col = max(col, 0.0);
+  float a = clamp(max(max(col.r, col.g), col.b), 0.0, 1.0);
+  return vec4(col, a);
+}
+`;

package/src/engine/look/particles.glsl.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared GPU-particle GLSL chunk.
+ *
+ * Solarbloom's drifting "motes" and Verdict's flung "droplets" are both
+ * point-sprite particle fields that differ only in their MOTION model (motes:
+ * outward drift + buoyancy + curl, with motion-blur streaks; droplets: a
+ * ballistic arc under gravity) and their styling. The cross-pollination plan
+ * asks for one parametric particle module behind a shared include + params.
+ *
+ * Here we extract the parts that were duplicated verbatim between the two: the
+ * per-particle soft round sprite (`particleSprite`), the ballistic position
+ * (`ballisticPos`), and the standard fade-in/out over a particle's life
+ * (`particleFade`). Each effect keeps its own emit shape + motion (the part that
+ * is its identity) and composes these shared primitives, so the dot falloff,
+ * the gravity arc and the lifetime curve no longer drift between effects.
+ *
+ * Comic debris can adopt the same primitives later (deferred — noted in the
+ * plan as P2). Requires no other chunk.
+ */
+
+export const GLSL_PARTICLES = /* glsl */ `
+// Soft round particle sprite: an inverse-distance dot that, squared, gives the
+// glowing-photon falloff both motes and droplets use. \`d\` is distance to the
+// particle centre, \`size\` its radius in device px.
+float particleSprite(float d, float size){
+  float s = size / (d + size * 0.5);
+  return s * s;
+}
+
+// Ballistic arc: launch from \`origin\` along \`dir\` at \`speed\`, pulled down by
+// \`gravity\` (device px) over normalized particle life \`t\` (0..1). Screen y is
+// up, so gravity subtracts on y. Used by Verdict's flung ink droplets and any
+// effect that wants sparks thrown off an impact.
+vec2 ballisticPos(vec2 origin, vec2 dir, float speed, float gravity, float t){
+  return origin + dir * speed * t - vec2(0.0, 1.0) * gravity * t * t;
+}
+
+// Standard particle fade: ramps in fast then fades out across its life. \`t\` is
+// normalized particle life (0..1); \`tailPow\` shapes the decay (higher = longer
+// luminous body before it dims).
+float particleFade(float t, float tailPow){
+  return (1.0 - pow(t, tailPow)) * smoothstep(0.0, 0.08, t);
+}
+`;

package/src/engine/sdf.ts

@@ -0,0 +1,298 @@
+/**
+ * SVG path → signed-distance-field (SDF) baker + runtime decoder.
+ *
+ * This is the "geometry seam": an effect's icon outline lives in its `.dope` as
+ * an `svgPath` string (authored, host-swappable). A BUILD step (scripts/bake-sdf
+ * or scripts/pack-dope) rasterizes that path into a small, self-contained SDF and
+ * inlines it into the distributed `.dope` (a `data:`-style base64 blob, no remote
+ * fetch). At RUNTIME the effect only DECODES + SAMPLES the SDF — it never does a
+ * live path→SDF conversion — so swapping the path in the `.dope` changes the
+ * rendered icon with no shader edit.
+ *
+ * The SDF here is a stroked-outline distance field: distance to the path's
+ * centerline (a polyline flattened from the bezier/line segments), so the icon
+ * reads as a *drawn stroke in light* (a tick, a cross, a custom mark), matching
+ * the "drawn-in-light" language of the built-ins. The field is signed only in the
+ * stroke sense (we store distance-to-stroke, with a coverage falloff applied at
+ * sample time by the shader against the declared stroke width), which is all the
+ * "drawn in light" look needs and keeps the bake free of robust point-in-polygon
+ * winding for arbitrary self-intersecting glyphs.
+ *
+ * Encoding (intentionally tiny, dependency-free, portable to Swift):
+ *   - a fixed-size square grid of `size`×`size` 8-bit samples,
+ *   - each sample = clamp(distance / range, 0..1) * 255 (0 = on the stroke,
+ *     255 = `range` author-units or more away),
+ *   - serialized as a 4-byte header (magic 'D','S', size hi/lo) + the bytes,
+ *     base64-encoded. `range` + `viewBox` travel as JSON next to the blob.
+ */
+
+/** A flattened 2D point in author/viewBox units. */
+export interface Pt {
+  x: number;
+  y: number;
+}
+
+/**
+ * Parse a (subset of) SVG path data into a list of polylines (each a list of
+ * points in author units). Supports absolute + relative M/L/H/V/C/Q/Z (the
+ * commands a designer's checkmark / cross / icon outline actually use). Curves
+ * are flattened to line segments at `steps` subdivisions — plenty for an SDF.
+ */
+export function parseSvgPath(d: string, steps = 24): Pt[][] {
+  const polylines: Pt[][] = [];
+  let cur: Pt[] = [];
+  let cx = 0;
+  let cy = 0;
+  let startX = 0;
+  let startY = 0;
+
+  // Tokenize into command letters + numeric runs.
+  const tokens = d.match(/[a-zA-Z]|-?\d*\.?\d+(?:e[-+]?\d+)?/gi) ?? [];
+  let i = 0;
+  const num = (): number => Number(tokens[i++]);
+  const has = (): boolean => i < tokens.length && /^-?\.?\d/.test(tokens[i]!);
+
+  const push = (x: number, y: number): void => {
+    cur.push({ x, y });
+    cx = x;
+    cy = y;
+  };
+  const flushCur = (): void => {
+    if (cur.length > 1) polylines.push(cur);
+    cur = [];
+  };
+
+  let cmd = "";
+  while (i < tokens.length) {
+    const t = tokens[i]!;
+    if (/[a-zA-Z]/.test(t)) {
+      cmd = t;
+      i++;
+    } else if (!cmd) {
+      i++;
+      continue;
+    }
+    const rel = cmd === cmd.toLowerCase();
+    switch (cmd.toUpperCase()) {
+      case "M": {
+        flushCur();
+        const x = num() + (rel ? cx : 0);
+        const y = num() + (rel ? cy : 0);
+        startX = x;
+        startY = y;
+        push(x, y);
+        cmd = rel ? "l" : "L"; // subsequent pairs are implicit lineto
+        while (has()) {
+          const lx = num() + (rel ? cx : 0);
+          const ly = num() + (rel ? cy : 0);
+          push(lx, ly);
+        }
+        break;
+      }
+      case "L": {
+        do {
+          const x = num() + (rel ? cx : 0);
+          const y = num() + (rel ? cy : 0);
+          push(x, y);
+        } while (has());
+        break;
+      }
+      case "H": {
+        do {
+          const x = num() + (rel ? cx : 0);
+          push(x, cy);
+        } while (has());
+        break;
+      }
+      case "V": {
+        do {
+          const y = num() + (rel ? cy : 0);
+          push(cx, y);
+        } while (has());
+        break;
+      }
+      case "C": {
+        do {
+          const x1 = num() + (rel ? cx : 0);
+          const y1 = num() + (rel ? cy : 0);
+          const x2 = num() + (rel ? cx : 0);
+          const y2 = num() + (rel ? cy : 0);
+          const x = num() + (rel ? cx : 0);
+          const y = num() + (rel ? cy : 0);
+          const p0 = { x: cx, y: cy };
+          for (let s = 1; s <= steps; s++) {
+            const u = s / steps;
+            const mt = 1 - u;
+            const bx =
+              mt * mt * mt * p0.x + 3 * mt * mt * u * x1 + 3 * mt * u * u * x2 + u * u * u * x;
+            const by =
+              mt * mt * mt * p0.y + 3 * mt * mt * u * y1 + 3 * mt * u * u * y2 + u * u * u * y;
+            push(bx, by);
+          }
+        } while (has());
+        break;
+      }
+      case "Q": {
+        do {
+          const x1 = num() + (rel ? cx : 0);
+          const y1 = num() + (rel ? cy : 0);
+          const x = num() + (rel ? cx : 0);
+          const y = num() + (rel ? cy : 0);
+          const p0 = { x: cx, y: cy };
+          for (let s = 1; s <= steps; s++) {
+            const u = s / steps;
+            const mt = 1 - u;
+            const bx = mt * mt * p0.x + 2 * mt * u * x1 + u * u * x;
+            const by = mt * mt * p0.y + 2 * mt * u * y1 + u * u * y;
+            push(bx, by);
+          }
+        } while (has());
+        break;
+      }
+      case "Z": {
+        if (cur.length) {
+          push(startX, startY);
+          flushCur();
+        }
+        break;
+      }
+      default:
+        // Unknown command — skip its number to avoid an infinite loop.
+        if (has()) num();
+        break;
+    }
+  }
+  flushCur();
+  return polylines;
+}
+
+/** Distance from point p to segment a→b, in author units. */
+function distToSeg(px: number, py: number, ax: number, ay: number, bx: number, by: number): number {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const len2 = dx * dx + dy * dy;
+  let t = len2 > 1e-9 ? ((px - ax) * dx + (py - ay) * dy) / len2 : 0;
+  t = t < 0 ? 0 : t > 1 ? 1 : t;
+  const qx = ax + dx * t;
+  const qy = ay + dy * t;
+  return Math.hypot(px - qx, py - qy);
+}
+
+/** A baked SDF: a square grid + the metadata a sampler needs. */
+export interface BakedSdf {
+  /** Grid resolution (square). */
+  size: number;
+  /** Author-units of distance that map to the full 0..255 byte range. */
+  range: number;
+  /** The viewBox the path was authored in: [minX, minY, w, h]. */
+  viewBox: [number, number, number, number];
+  /**
+   * A `data:` URI carrying the header + size×size 8-bit distance bytes (base64).
+   * A `data:` URI (not a remote/absolute ref) keeps the `.dope` self-contained
+   * and passes the loader's standalone guard. The runtime decodes + samples it.
+   */
+  data: string;
+}
+
+/** The MIME used for the inline SDF `data:` URI. */
+const SDF_MIME = "application/octet-stream";
+const SDF_DATA_PREFIX = `data:${SDF_MIME};base64,`;
+
+const MAGIC0 = 0x44; // 'D'
+const MAGIC1 = 0x53; // 'S'
+
+/** Encode raw bytes to base64 in both Node and the browser. */
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!);
+  // eslint-disable-next-line no-undef
+  return btoa(bin);
+}
+
+/** Decode base64 to raw bytes in both Node and the browser. */
+function base64ToBytes(b64: string): Uint8Array {
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(b64, "base64"));
+  // eslint-disable-next-line no-undef
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * BAKE: rasterize an SVG path into a stroked-distance SDF. Pure + deterministic.
+ * `size` is the grid resolution; `range` is how many author-units of distance map
+ * to the full byte range (a larger range = a softer, wider usable falloff). The
+ * path is normalized into a centered square that preserves its aspect inside the
+ * grid, leaving a small margin so the stroke + its glow never clip the edge.
+ */
+export function bakeSdf(
+  svgPath: string,
+  viewBox: [number, number, number, number],
+  size = 64,
+  range = 18,
+): BakedSdf {
+  const polylines = parseSvgPath(svgPath);
+  const [vx, vy, vw, vh] = viewBox;
+  const bytes = new Uint8Array(size * size);
+
+  // Map a grid cell center to author/viewBox coordinates (y stays top-down, the
+  // shader flips as needed). The whole viewBox maps to the grid 0..size.
+  for (let gy = 0; gy < size; gy++) {
+    for (let gx = 0; gx < size; gx++) {
+      const ax = vx + ((gx + 0.5) / size) * vw;
+      const ay = vy + ((gy + 0.5) / size) * vh;
+      let best = Infinity;
+      for (const poly of polylines) {
+        for (let k = 0; k + 1 < poly.length; k++) {
+          const d = distToSeg(ax, ay, poly[k]!.x, poly[k]!.y, poly[k + 1]!.x, poly[k + 1]!.y);
+          if (d < best) best = d;
+        }
+      }
+      const norm = best === Infinity ? 1 : Math.min(1, best / range);
+      bytes[gy * size + gx] = Math.round(norm * 255);
+    }
+  }
+
+  const header = new Uint8Array(4);
+  header[0] = MAGIC0;
+  header[1] = MAGIC1;
+  header[2] = (size >> 8) & 0xff;
+  header[3] = size & 0xff;
+  const blob = new Uint8Array(header.length + bytes.length);
+  blob.set(header, 0);
+  blob.set(bytes, header.length);
+
+  return { size, range, viewBox, data: SDF_DATA_PREFIX + bytesToBase64(blob) };
+}
+
+/** A decoded SDF ready to upload: the raw single-channel bytes + its size. */
+export interface DecodedSdf {
+  size: number;
+  range: number;
+  viewBox: [number, number, number, number];
+  /** size×size single-channel (0..255) distance bytes. */
+  bytes: Uint8Array;
+}
+
+/**
+ * DECODE a baked SDF blob back to its raw distance bytes. Validates the magic +
+ * the declared size against the byte count. Used by the runtime to upload an
+ * `R8`/alpha texture — the runtime SAMPLES this; it never re-bakes.
+ */
+export function decodeSdf(baked: BakedSdf): DecodedSdf {
+  const b64 = baked.data.startsWith(SDF_DATA_PREFIX)
+    ? baked.data.slice(SDF_DATA_PREFIX.length)
+    : baked.data; // tolerate a bare base64 blob too
+  const blob = base64ToBytes(b64);
+  if (blob.length < 4 || blob[0] !== MAGIC0 || blob[1] !== MAGIC1) {
+    throw new Error("dope: not a baked SDF blob (bad magic)");
+  }
+  const size = (blob[2]! << 8) | blob[3]!;
+  const bytes = blob.subarray(4);
+  if (bytes.length !== size * size) {
+    throw new Error(`dope: SDF size mismatch (header ${size}^2 != ${bytes.length} bytes)`);
+  }
+  return { size, range: baked.range, viewBox: baked.viewBox, bytes: bytes.slice() };
+}

package/src/engine/seed.ts

@@ -0,0 +1,23 @@
+/** Deterministic, seedable PRNG so a given `seed` always yields the same look. */
+
+export type Rng = () => number;
+
+/**
+ * mulberry32 — tiny, fast, good-enough-for-visuals PRNG. Returns values in
+ * [0, 1). Deterministic for a given 32-bit seed.
+ */
+export function mulberry32(seed: number): Rng {
+  let a = seed >>> 0;
+  return function next(): number {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** A fresh 32-bit seed — used when the caller doesn't pin one. */
+export function randomSeed(): number {
+  return (Math.random() * 0xffffffff) >>> 0;
+}

package/src/engine/shadow.ts

@@ -0,0 +1,66 @@
+/**
+ * Shadow-pass geometry — the pure math that turns an effect's amplitude,
+ * "height" above the page, and stylization into the offset / softness /
+ * strength of the cast soft shadow. Kept framework- and GL-free so it can be
+ * unit-tested and reused by any effect that adopts the multiply shadow layer.
+ *
+ * Conventions (device pixels, gl coords where Y is UP):
+ *   - The implied key light sits up-and-left of the floating effect, so the
+ *     shadow falls DOWN-and-right: offset = (+x, -y).
+ *   - `offset` grows with the occluder's height and with amplitude (a brighter,
+ *     higher source throws a longer shadow).
+ *   - `soft` (penumbra blur radius) is larger for a soft photoreal source and
+ *     tightens toward the hard graphic drop-shadow of the cel end.
+ *   - `strength` is the max darkening of the multiply layer (0 = none); kept
+ *     ambient-occlusion subtle, a touch firmer toward cel.
+ */
+
+export interface ShadowGeometry {
+  /** Silhouette offset in device px, gl coords (x right, y up). */
+  offsetX: number;
+  offsetY: number;
+  /** Penumbra blur tap radius in device px. */
+  soft: number;
+  /** Max multiply darkening, 0..1. */
+  strength: number;
+}
+
+export interface ShadowInput {
+  /** Smaller canvas dimension in device px. */
+  minDim: number;
+  /**
+   * The occluder's "height" above the page as a fraction of `minDim` — bigger
+   * forms read as floating higher and cast longer, softer shadows. For
+   * Solarbloom this is the bloom radius fraction; for Verdict, the stroke scale.
+   */
+  heightFrac: number;
+  /** Envelope amplitude (peaks > 1). */
+  amp: number;
+  /** Stylization 0..1 (photoreal → cel). */
+  style: number;
+}
+
+const clamp = (x: number, lo: number, hi: number): number =>
+  x < lo ? lo : x > hi ? hi : x;
+
+export function shadowGeometry({ minDim, heightFrac, amp, style }: ShadowInput): ShadowGeometry {
+  const height = heightFrac * minDim;
+  // Offset length: scales with height and (clamped) amplitude. A meaningful
+  // drop so the silhouette clears the bright core (which the screen light owns)
+  // and lands as a distinct shadow on the UI beside/below it.
+  const off = height * 0.16 * (0.6 + 0.5 * Math.min(amp, 1.5));
+  // Penumbra: wide & soft when photoreal, tight when cel; always a small floor.
+  const soft = minDim * 0.014 * (1 - 0.6 * style) + minDim * 0.005;
+  // Darkening of the multiply layer. Kept ambient at the soft end, firmer (a
+  // graphic drop-shadow) toward cel. Reads clearly where it falls on the
+  // lighter raised faces / the white primary button.
+  const strength = clamp(0.6 * (0.8 + 0.45 * style), 0, 1);
+  return {
+    // Down-and-right: x positive, y negative (gl Y up). x is a fraction of the
+    // drop so the shadow leans, not straight down.
+    offsetX: off * 0.55,
+    offsetY: -off,
+    soft,
+    strength,
+  };
+}

package/src/engine/tempo.ts

@@ -0,0 +1,54 @@
+/**
+ * Animation tempo PRIMITIVES — the generic easing + envelope building blocks
+ * shared across effects.
+ *
+ * Linear motion reads as unnatural, so everything here is eased. These are the
+ * GENERIC primitives only: each effect's BESPOKE envelope (the comic slam, the
+ * fail stamp/shake, the heartburst lub-dub, the lightning strike/strobe, the
+ * solarbloom check draw, the inkstroke stroke draw, …) lives in that effect's
+ * own `<name>-tempo.ts` inside `@dopaminefx/effect-<name>`, built on top of these.
+ */
+
+/**
+ * Coarse animation step (ms) for the hand-drawn "animate on twos" look at full
+ * whimsy — ~12 updates/sec, i.e. 24fps on twos. Motion is snapped toward this
+ * grid as style rises (see the pass-runner), giving discrete, posed beats
+ * instead of smooth interpolation.
+ */
+export const NPR_TIME_STEP_MS = 1000 / 12;
+
+/** Clamp a value into [0, 1]. */
+export const clamp01 = (x: number): number => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+/** Classic ease-out cubic — quick start, gentle settle. */
+export function easeOutCubic(x: number): number {
+  const t = clamp01(x);
+  return 1 - Math.pow(1 - t, 3);
+}
+
+/**
+ * Ease-out "back" — overshoots past 1 then settles exactly to 1 at x=1. This is
+ * the held-breath release. `overshoot` scales how far past 1 it swells.
+ */
+export function easeOutBack(x: number, overshoot = 1): number {
+  const t = clamp01(x);
+  const c1 = 1.70158 * overshoot;
+  const c3 = c1 + 1;
+  return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+}
+
+/**
+ * Bloom amplitude over normalized life `t` ∈ [0, 1].
+ * Fast attack with overshoot in the first ~18%, then a long decay to zero.
+ * `envelope(0) === 0`, `envelope(1) === 0`, peak > 1 during the attack.
+ */
+export function envelope(t: number, overshoot = 1): number {
+  if (t <= 0 || t >= 1) return 0;
+  const attack = 0.18;
+  if (t < attack) {
+    return easeOutBack(t / attack, overshoot);
+  }
+  const x = (t - attack) / (1 - attack);
+  // Decays from 1 → 0; exponent > 1 keeps a slow, luxurious tail.
+  return Math.pow(1 - x, 1.6);
+}