@dopaminefx/effect-dots 0.1.0

package/dist/dots-shader.d.ts

@@ -0,0 +1,38 @@
+/**
+ * GLSL ES 3.00 source for **Dots** — Dopamine's calm ambient "thinking" indicator.
+ *
+ * Governing metaphor: a centred ROW of soft luminous dots, centred on the action
+ * point (`uOrigin`). They gently BREATHE together (a slow sine on radius +
+ * brightness) while a brightness PULSE travels across the row in sequence (the
+ * classic "typing… / loading…" read). Electric / serene OKLCH hues from the
+ * seeded palette.
+ *
+ * Dopamine's SECOND CONTINUOUS effect (after halo). Like halo it rides the
+ * first-class `tempo.loop` contract:
+ *   - The `.dope` declares `tempo.loop.periodMs = 1000`; the runner derives the
+ *     standard periodic clocks from it each frame — `uPhase` (normalized loop
+ *     phase in [0, 1)) and `uLoopS` (seconds within the loop) — off the SAME
+ *     "animate on twos"-snapped clock as `uTimeS`. The parser validates the seam
+ *     invariants (the period is 12 on-twos steps; `durationMs` 4000 = 4 whole
+ *     periods), so the frame at `t == durationMs` equals `t == 0` at EVERY whimsy.
+ *   - ALL animation here is a periodic function of `uPhase`: `sin(TAU·uPhase)`
+ *     for the breathe, and a chase whose head position is `fract(uPhase)` so it
+ *     winds exactly ONE turn around the row per period and rejoins seamlessly.
+ *     Nothing reads a monotonic clock (`uLife`/`uTimeS`), so every period
+ *     boundary is seamless.
+ *   - `frame()` returns a STEADY periodic `amp = 0.85 + 0.15·sin(TAU·phase)`
+ *     (never `envelope(life)`), so there is no one-shot fade to break the seam.
+ *   - The conductor re-arms the effect at `durationMs` instead of tearing down;
+ *     the host stops it via the play handle (and can pause/resume it drift-free).
+ *
+ * whimsy == uStyle:
+ *   0 = photoreal soft glow — gaussian dots + a smooth feathered chase.
+ *   1 = cel / flat — the dots become hard flat discs and the chase snaps into a
+ *       single posterized "lit" dot stepping along the row.
+ */
+/** Compile-time cap on the dot count: BOTH the GLSL `#define MAX_DOTS` (below)
+ * and the integer-clamp const the `.dope` mapping references (`MAX_DOTS`). */
+export declare const MAX_DOTS = 7;
+export declare const DOTS_VERTEX_SRC = "#version 300 es\nout vec2 vUv;\nvoid main() {\n  // Single full-screen triangle from gl_VertexID \u2014 no vertex buffers needed.\n  vec2 pos = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n  vUv = pos;\n  gl_Position = vec4(pos * 2.0 - 1.0, 0.0, 1.0);\n}";
+export declare const DOTS_FRAGMENT_SRC = "#version 300 es\nprecision highp float;\nout vec4 fragColor;\n\nuniform vec2  uResolution;    // device pixels\nuniform vec2  uOrigin;        // row centre, gl coords (y up)\nuniform float uAmp;           // STEADY periodic breathe gate (~0.85..1.0), not an envelope\nuniform float uPhase;         // normalized loop phase [0,1) (tempo.loop) \u2014 drives ALL motion\nuniform float uLoopS;         // seconds within the current loop (the dither's temporal seed)\nuniform float uExposure;\nuniform float uDotCount;      // number of dots in the row (clamped to MAX_DOTS)\nuniform float uDotRadius;     // dot radius as a fraction of min viewport dim\nuniform float uDotGap;        // centre-to-centre spacing as a fraction of min viewport dim\nuniform float uBreathe;       // 0..1 breathe depth (radius/brightness sine swing)\nuniform float uChase;         // 0..1+ sharpness of the traveling pulse (tighter = livelier)\nuniform float uGlow;          // 0..1 ambient under-glow brightness\nuniform float uStyle;         // 0..1 photoreal soft glow -> cel/flat discs (whimsy)\nuniform float uShadow;        // 0 = light pass (screen), 1 = shadow pass (multiply)\nuniform vec2  uShadowOffset;  // device-px offset of the cast silhouette (away from light)\nuniform float uShadowSoft;    // penumbra softness in device px (blur tap radius)\nuniform float uShadowStrength;// 0..1 max darkening of the multiply layer\nuniform vec3  uC0;            // dot core color\nuniform vec3  uC1;            // mid\nuniform vec3  uC2;            // pulse accent\n\n#define MAX_DOTS 7\n\n\n#define TAU 6.28318530718\n\n\nfloat hash11(float p){ p = fract(p * 0.1031); p *= p + 33.33; p *= p + p; return fract(p); }\nvec2 hash21(float p){\n  vec3 p3 = fract(vec3(p) * vec3(0.1031, 0.1030, 0.0973));\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.xx + p3.yz) * p3.zy);\n}\n\n\nvec3 paletteMix(float t){\n  t = clamp(t, 0.0, 1.0);\n  return t < 0.5 ? mix(uC0, uC1, t * 2.0) : mix(uC1, uC2, (t - 0.5) * 2.0);\n}\n\n\nvec3 tonemapACES(vec3 x){\n  const float a = 2.51, b = 0.03, c = 2.43, d = 0.59, e = 0.14;\n  return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0);\n}\n\n\nvec3 ditherAdd(vec3 col, vec2 frag, float t, float fade){\n  float dz = hash11(dot(frag, vec2(12.989, 78.233)) + t) - 0.5;\n  return col + (dz / 255.0) * fade;\n}\n\n\n// The live count, clamped to the compile-time cap so the loop bound is constant.\nint dotCount(){\n  return int(clamp(uDotCount, 1.0, float(MAX_DOTS)) + 0.5);\n}\n\n// The breathing dot radius. One slow sine per loop period swings the radius by\n// \u00B1uBreathe\u00B7radius around the base \u2014 the gentle pulse \"breath\". Periodic in\n// uPhase, so it returns to its t=0 value at every seam.\nfloat liveRadius(){\n  return uDotRadius * (1.0 + sin(TAU * uPhase) * uBreathe * 0.45);\n}\n\n// The normalized x-centre of dot i: a row of dotCount dots, spaced uDotGap apart,\n// centred on the origin (so the whole row is symmetric about x = 0).\nfloat dotCenterX(int i, int count){\n  float c = float(count);\n  return (float(i) - (c - 1.0) * 0.5) * uDotGap;\n}\n\n// 0..1 \"lit\" weight of dot i under the traveling pulse. The pulse HEAD winds one\n// full turn around the row per period (head = fract(uPhase) -> seamless); each\n// dot lights as the head sweeps over its slot, with a comet-like falloff set by\n// uChase. Wrapped distance keeps it continuous across the seam.\nfloat pulseLit(int i, int count){\n  float head = fract(uPhase) * float(count);          // 0..count head position\n  float d = abs(float(i) + 0.5 - head);\n  d = min(d, float(count) - d);                        // wrap around the row\n  float sharp = mix(0.9, 2.4, clamp(uChase, 0.0, 1.5) / 1.5);\n  return exp(-(d * d) * sharp);\n}\n\n// The whole row's emitted light at a fragment.\nvec3 dotsLight(vec2 frag, float minDim){\n  vec2 rel = (frag - uOrigin) / minDim;       // normalized, row-centred (y up)\n  int count = dotCount();\n  float radius = max(liveRadius(), 1e-3);\n\n  // The breathe also gently modulates overall brightness (brighter on the inhale).\n  float breatheB = 1.0 + sin(TAU * uPhase) * uBreathe * 0.5;\n  float gain = uAmp * uExposure * breatheB;\n\n  vec3 col = vec3(0.0);\n  for (int i = 0; i < MAX_DOTS; i++) {\n    if (i >= count) break;\n    float cx = dotCenterX(i, count);\n    vec2 dpos = rel - vec2(cx, 0.0);\n    float dist = length(dpos);\n\n    // Per-dot hue register: stops walk along the row (C0 -> C1 -> C2), so the row\n    // reads as a coherent gradient rather than identical clones.\n    float tcol = (count > 1) ? float(i) / float(count - 1) : 0.5;\n    vec3 dotCol = paletteMix(clamp(tcol, 0.0, 1.0));\n\n    // The pulse brightens whichever dot the head is sweeping over.\n    float lit = pulseLit(i, count);\n    float bright = 0.35 + 0.65 * lit;          // dim base, bright under the pulse\n\n    // 1. CORE: a soft gaussian dot.\n    float cov = exp(-(dist * dist) / (2.0 * radius * radius));\n    col += dotCol * cov * gain * bright;\n\n    // 2. GLOW: a wider, dim ambient halo under each dot.\n    float gr = radius * 2.6;\n    float glow = exp(-(dist * dist) / (2.0 * gr * gr));\n    col += mix(dotCol, uC2, lit * 0.4) * glow * uGlow * gain * 0.3 * bright;\n  }\n  return col;\n}\n\n// ---------------------------------------------------------------------------\n// SHADOW silhouette \u2014 the dots are small floating discs, so each casts a faint\n// soft occlusion. Sample the row coverage at the offset shadow point and darken\n// in proportion, kept subtle (small discs throw little shadow).\nfloat dotsOcclusion(vec2 frag, float minDim){\n  vec2 rel = (frag - uOrigin) / minDim;\n  int count = dotCount();\n  float radius = max(liveRadius(), 1e-3);\n  float occ = 0.0;\n  for (int i = 0; i < MAX_DOTS; i++) {\n    if (i >= count) break;\n    vec2 dpos = rel - vec2(dotCenterX(i, count), 0.0);\n    float dist = length(dpos);\n    occ = max(occ, exp(-(dist * dist) / (2.0 * radius * radius)));\n  }\n  return clamp(occ * uAmp, 0.0, 1.0);\n}\n\nvec4 dotsShadowColor(vec2 frag, float minDim){\n  vec2 sp = frag - uShadowOffset;\n  float soft = uShadowSoft;\n  float occ = dotsOcclusion(sp, minDim);\n  occ += dotsOcclusion(sp + vec2( soft, 0.0), minDim);\n  occ += dotsOcclusion(sp + vec2(-soft, 0.0), minDim);\n  occ += dotsOcclusion(sp + vec2(0.0,  soft), minDim);\n  occ += dotsOcclusion(sp + vec2(0.0, -soft), minDim);\n  occ /= 5.0;\n  float dark = clamp(occ, 0.0, 1.0) * uShadowStrength * 0.5;\n  vec3 tint = mix(vec3(1.0), 0.6 + 0.4 * normalize(uC0 + 1e-3), 0.2);\n  vec3 mul = mix(vec3(1.0), tint, dark);\n  return vec4(mul, 1.0);\n}\n\nvoid main(){\n  vec2 frag = gl_FragCoord.xy;\n  vec2 res = uResolution;\n  float minDim = min(res.x, res.y);\n\n  if (uShadow > 0.5) {\n    fragColor = dotsShadowColor(frag, minDim);\n    return;\n  }\n\n  vec3 col = dotsLight(frag, minDim);\n\n  // ---- Tone + finishing ----\n  col = tonemapACES(col * 0.95);\n\n  // ---- Non-photoreal pass: cel / flat discs (whimsy). ----\n  // Toward the cel end the soft gaussians become hard flat DISCS and the chase\n  // snaps to a single posterized \"lit\" dot. The pass-runner already steps the\n  // clock \"on twos\" (periodic \u2014 tempo.loop tiles the grid \u2014 so the loop seam\n  // survives); here we flatten the tone.\n  if (uStyle > 0.001) {\n    vec2 rel = (frag - uOrigin) / minDim;\n    int count = dotCount();\n    float radius = max(liveRadius(), 1e-3);\n    float breatheB = 1.0 + sin(TAU * uPhase) * uBreathe * 0.5;\n    float gain = uAmp * uExposure * breatheB;\n    vec3 cel = vec3(0.0);\n    for (int i = 0; i < MAX_DOTS; i++) {\n      if (i >= count) break;\n      vec2 dpos = rel - vec2(dotCenterX(i, count), 0.0);\n      float dist = length(dpos);\n      float disc = 1.0 - smoothstep(radius * 0.85, radius, dist);   // hard flat disc\n      float tcol = (count > 1) ? float(i) / float(count - 1) : 0.5;\n      vec3 dotCol = clamp(paletteMix(clamp(tcol, 0.0, 1.0)) * 1.25, 0.0, 1.2);\n      float lit = pulseLit(i, count);\n      float litStep = step(0.6, lit);                                // one dot lit at a time\n      cel += dotCol * disc * (0.4 + 0.6 * litStep)\n           + mix(uC2, vec3(1.0), 0.5) * disc * litStep * 0.4;\n    }\n    cel *= gain;\n    col = mix(col, cel, uStyle);\n  }\n\n  // Ordered dither (~1/255) to kill banding the screen blend reveals; faded out\n  // toward the cel end where hard discs are intended. Seeded by the LOOP clock,\n  // so even the dither field repeats exactly at the seam.\n  col = ditherAdd(col, frag, uLoopS, 1.0 - uStyle);\n\n  fragColor = vec4(max(col, 0.0), 1.0);\n}";
+//# sourceMappingURL=dots-shader.d.ts.map

package/dist/dots-shader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dots-shader.d.ts","sourceRoot":"","sources":["../src/dots-shader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAUH;8EAC8E;AAC9E,eAAO,MAAM,QAAQ,IAAI,CAAC;AAE1B,eAAO,MAAM,eAAe,oRAO1B,CAAC;AAEH,eAAO,MAAM,iBAAiB,06QAwL5B,CAAC"}

package/dist/dots-shader.js

@@ -0,0 +1,230 @@
+/**
+ * GLSL ES 3.00 source for **Dots** — Dopamine's calm ambient "thinking" indicator.
+ *
+ * Governing metaphor: a centred ROW of soft luminous dots, centred on the action
+ * point (`uOrigin`). They gently BREATHE together (a slow sine on radius +
+ * brightness) while a brightness PULSE travels across the row in sequence (the
+ * classic "typing… / loading…" read). Electric / serene OKLCH hues from the
+ * seeded palette.
+ *
+ * Dopamine's SECOND CONTINUOUS effect (after halo). Like halo it rides the
+ * first-class `tempo.loop` contract:
+ *   - The `.dope` declares `tempo.loop.periodMs = 1000`; the runner derives the
+ *     standard periodic clocks from it each frame — `uPhase` (normalized loop
+ *     phase in [0, 1)) and `uLoopS` (seconds within the loop) — off the SAME
+ *     "animate on twos"-snapped clock as `uTimeS`. The parser validates the seam
+ *     invariants (the period is 12 on-twos steps; `durationMs` 4000 = 4 whole
+ *     periods), so the frame at `t == durationMs` equals `t == 0` at EVERY whimsy.
+ *   - ALL animation here is a periodic function of `uPhase`: `sin(TAU·uPhase)`
+ *     for the breathe, and a chase whose head position is `fract(uPhase)` so it
+ *     winds exactly ONE turn around the row per period and rejoins seamlessly.
+ *     Nothing reads a monotonic clock (`uLife`/`uTimeS`), so every period
+ *     boundary is seamless.
+ *   - `frame()` returns a STEADY periodic `amp = 0.85 + 0.15·sin(TAU·phase)`
+ *     (never `envelope(life)`), so there is no one-shot fade to break the seam.
+ *   - The conductor re-arms the effect at `durationMs` instead of tearing down;
+ *     the host stops it via the play handle (and can pause/resume it drift-free).
+ *
+ * whimsy == uStyle:
+ *   0 = photoreal soft glow — gaussian dots + a smooth feathered chase.
+ *   1 = cel / flat — the dots become hard flat discs and the chase snaps into a
+ *       single posterized "lit" dot stepping along the row.
+ */
+import { GLSL_CONSTANTS, GLSL_DITHER, GLSL_HASH, GLSL_PALETTE_MIX, GLSL_TONEMAP_ACES, } from "@dopaminefx/core";
+/** Compile-time cap on the dot count: BOTH the GLSL `#define MAX_DOTS` (below)
+ * and the integer-clamp const the `.dope` mapping references (`MAX_DOTS`). */
+export const MAX_DOTS = 7;
+export const DOTS_VERTEX_SRC = /* glsl */ `#version 300 es
+out vec2 vUv;
+void main() {
+  // Single full-screen triangle from gl_VertexID — no vertex buffers needed.
+  vec2 pos = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  vUv = pos;
+  gl_Position = vec4(pos * 2.0 - 1.0, 0.0, 1.0);
+}`;
+export const DOTS_FRAGMENT_SRC = /* glsl */ `#version 300 es
+precision highp float;
+out vec4 fragColor;
+
+uniform vec2  uResolution;    // device pixels
+uniform vec2  uOrigin;        // row centre, gl coords (y up)
+uniform float uAmp;           // STEADY periodic breathe gate (~0.85..1.0), not an envelope
+uniform float uPhase;         // normalized loop phase [0,1) (tempo.loop) — drives ALL motion
+uniform float uLoopS;         // seconds within the current loop (the dither's temporal seed)
+uniform float uExposure;
+uniform float uDotCount;      // number of dots in the row (clamped to MAX_DOTS)
+uniform float uDotRadius;     // dot radius as a fraction of min viewport dim
+uniform float uDotGap;        // centre-to-centre spacing as a fraction of min viewport dim
+uniform float uBreathe;       // 0..1 breathe depth (radius/brightness sine swing)
+uniform float uChase;         // 0..1+ sharpness of the traveling pulse (tighter = livelier)
+uniform float uGlow;          // 0..1 ambient under-glow brightness
+uniform float uStyle;         // 0..1 photoreal soft glow -> cel/flat discs (whimsy)
+uniform float uShadow;        // 0 = light pass (screen), 1 = shadow pass (multiply)
+uniform vec2  uShadowOffset;  // device-px offset of the cast silhouette (away from light)
+uniform float uShadowSoft;    // penumbra softness in device px (blur tap radius)
+uniform float uShadowStrength;// 0..1 max darkening of the multiply layer
+uniform vec3  uC0;            // dot core color
+uniform vec3  uC1;            // mid
+uniform vec3  uC2;            // pulse accent
+
+#define MAX_DOTS ${MAX_DOTS}
+
+${GLSL_CONSTANTS}
+${GLSL_HASH}
+${GLSL_PALETTE_MIX}
+${GLSL_TONEMAP_ACES}
+${GLSL_DITHER}
+
+// The live count, clamped to the compile-time cap so the loop bound is constant.
+int dotCount(){
+  return int(clamp(uDotCount, 1.0, float(MAX_DOTS)) + 0.5);
+}
+
+// The breathing dot radius. One slow sine per loop period swings the radius by
+// ±uBreathe·radius around the base — the gentle pulse "breath". Periodic in
+// uPhase, so it returns to its t=0 value at every seam.
+float liveRadius(){
+  return uDotRadius * (1.0 + sin(TAU * uPhase) * uBreathe * 0.45);
+}
+
+// The normalized x-centre of dot i: a row of dotCount dots, spaced uDotGap apart,
+// centred on the origin (so the whole row is symmetric about x = 0).
+float dotCenterX(int i, int count){
+  float c = float(count);
+  return (float(i) - (c - 1.0) * 0.5) * uDotGap;
+}
+
+// 0..1 "lit" weight of dot i under the traveling pulse. The pulse HEAD winds one
+// full turn around the row per period (head = fract(uPhase) -> seamless); each
+// dot lights as the head sweeps over its slot, with a comet-like falloff set by
+// uChase. Wrapped distance keeps it continuous across the seam.
+float pulseLit(int i, int count){
+  float head = fract(uPhase) * float(count);          // 0..count head position
+  float d = abs(float(i) + 0.5 - head);
+  d = min(d, float(count) - d);                        // wrap around the row
+  float sharp = mix(0.9, 2.4, clamp(uChase, 0.0, 1.5) / 1.5);
+  return exp(-(d * d) * sharp);
+}
+
+// The whole row's emitted light at a fragment.
+vec3 dotsLight(vec2 frag, float minDim){
+  vec2 rel = (frag - uOrigin) / minDim;       // normalized, row-centred (y up)
+  int count = dotCount();
+  float radius = max(liveRadius(), 1e-3);
+
+  // The breathe also gently modulates overall brightness (brighter on the inhale).
+  float breatheB = 1.0 + sin(TAU * uPhase) * uBreathe * 0.5;
+  float gain = uAmp * uExposure * breatheB;
+
+  vec3 col = vec3(0.0);
+  for (int i = 0; i < MAX_DOTS; i++) {
+    if (i >= count) break;
+    float cx = dotCenterX(i, count);
+    vec2 dpos = rel - vec2(cx, 0.0);
+    float dist = length(dpos);
+
+    // Per-dot hue register: stops walk along the row (C0 -> C1 -> C2), so the row
+    // reads as a coherent gradient rather than identical clones.
+    float tcol = (count > 1) ? float(i) / float(count - 1) : 0.5;
+    vec3 dotCol = paletteMix(clamp(tcol, 0.0, 1.0));
+
+    // The pulse brightens whichever dot the head is sweeping over.
+    float lit = pulseLit(i, count);
+    float bright = 0.35 + 0.65 * lit;          // dim base, bright under the pulse
+
+    // 1. CORE: a soft gaussian dot.
+    float cov = exp(-(dist * dist) / (2.0 * radius * radius));
+    col += dotCol * cov * gain * bright;
+
+    // 2. GLOW: a wider, dim ambient halo under each dot.
+    float gr = radius * 2.6;
+    float glow = exp(-(dist * dist) / (2.0 * gr * gr));
+    col += mix(dotCol, uC2, lit * 0.4) * glow * uGlow * gain * 0.3 * bright;
+  }
+  return col;
+}
+
+// ---------------------------------------------------------------------------
+// SHADOW silhouette — the dots are small floating discs, so each casts a faint
+// soft occlusion. Sample the row coverage at the offset shadow point and darken
+// in proportion, kept subtle (small discs throw little shadow).
+float dotsOcclusion(vec2 frag, float minDim){
+  vec2 rel = (frag - uOrigin) / minDim;
+  int count = dotCount();
+  float radius = max(liveRadius(), 1e-3);
+  float occ = 0.0;
+  for (int i = 0; i < MAX_DOTS; i++) {
+    if (i >= count) break;
+    vec2 dpos = rel - vec2(dotCenterX(i, count), 0.0);
+    float dist = length(dpos);
+    occ = max(occ, exp(-(dist * dist) / (2.0 * radius * radius)));
+  }
+  return clamp(occ * uAmp, 0.0, 1.0);
+}
+
+vec4 dotsShadowColor(vec2 frag, float minDim){
+  vec2 sp = frag - uShadowOffset;
+  float soft = uShadowSoft;
+  float occ = dotsOcclusion(sp, minDim);
+  occ += dotsOcclusion(sp + vec2( soft, 0.0), minDim);
+  occ += dotsOcclusion(sp + vec2(-soft, 0.0), minDim);
+  occ += dotsOcclusion(sp + vec2(0.0,  soft), minDim);
+  occ += dotsOcclusion(sp + vec2(0.0, -soft), minDim);
+  occ /= 5.0;
+  float dark = clamp(occ, 0.0, 1.0) * uShadowStrength * 0.5;
+  vec3 tint = mix(vec3(1.0), 0.6 + 0.4 * normalize(uC0 + 1e-3), 0.2);
+  vec3 mul = mix(vec3(1.0), tint, dark);
+  return vec4(mul, 1.0);
+}
+
+void main(){
+  vec2 frag = gl_FragCoord.xy;
+  vec2 res = uResolution;
+  float minDim = min(res.x, res.y);
+
+  if (uShadow > 0.5) {
+    fragColor = dotsShadowColor(frag, minDim);
+    return;
+  }
+
+  vec3 col = dotsLight(frag, minDim);
+
+  // ---- Tone + finishing ----
+  col = tonemapACES(col * 0.95);
+
+  // ---- Non-photoreal pass: cel / flat discs (whimsy). ----
+  // Toward the cel end the soft gaussians become hard flat DISCS and the chase
+  // snaps to a single posterized "lit" dot. The pass-runner already steps the
+  // clock "on twos" (periodic — tempo.loop tiles the grid — so the loop seam
+  // survives); here we flatten the tone.
+  if (uStyle > 0.001) {
+    vec2 rel = (frag - uOrigin) / minDim;
+    int count = dotCount();
+    float radius = max(liveRadius(), 1e-3);
+    float breatheB = 1.0 + sin(TAU * uPhase) * uBreathe * 0.5;
+    float gain = uAmp * uExposure * breatheB;
+    vec3 cel = vec3(0.0);
+    for (int i = 0; i < MAX_DOTS; i++) {
+      if (i >= count) break;
+      vec2 dpos = rel - vec2(dotCenterX(i, count), 0.0);
+      float dist = length(dpos);
+      float disc = 1.0 - smoothstep(radius * 0.85, radius, dist);   // hard flat disc
+      float tcol = (count > 1) ? float(i) / float(count - 1) : 0.5;
+      vec3 dotCol = clamp(paletteMix(clamp(tcol, 0.0, 1.0)) * 1.25, 0.0, 1.2);
+      float lit = pulseLit(i, count);
+      float litStep = step(0.6, lit);                                // one dot lit at a time
+      cel += dotCol * disc * (0.4 + 0.6 * litStep)
+           + mix(uC2, vec3(1.0), 0.5) * disc * litStep * 0.4;
+    }
+    cel *= gain;
+    col = mix(col, cel, uStyle);
+  }
+
+  // Ordered dither (~1/255) to kill banding the screen blend reveals; faded out
+  // toward the cel end where hard discs are intended. Seeded by the LOOP clock,
+  // so even the dither field repeats exactly at the seam.
+  col = ditherAdd(col, frag, uLoopS, 1.0 - uStyle);
+
+  fragColor = vec4(max(col, 0.0), 1.0);
+}`;
+//# sourceMappingURL=dots-shader.js.map

package/dist/dots-shader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dots-shader.js","sourceRoot":"","sources":["../src/dots-shader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EACL,cAAc,EACd,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B;8EAC8E;AAC9E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC;AAE1B,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;;;;;;;EAOxC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;mBAyBzB,QAAQ;;EAEzB,cAAc;EACd,SAAS;EACT,gBAAgB;EAChB,iBAAiB;EACjB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyJX,CAAC"}

package/dist/dots.dope.json

@@ -0,0 +1,331 @@
+{
+    "fmt": "dopamine-effect",
+    "v": "1.0.0",
+    "id": "dopamine.loading.dots",
+    "meta": {
+        "name": "Dots",
+        "description": "A calm ambient 'thinking' indicator: a centred row of soft luminous dots that gently breathe while a brightness PULSE travels across them in sequence (the classic typing / loading read). Dopamine's second CONTINUOUS effect — like halo it LOOPS SEAMLESSLY via the first-class tempo.loop contract: all motion is driven by the standard periodic clocks uPhase/uLoopS the runners derive from tempo.loop.periodMs (1000 ms). The parser validates the seam invariants (the period is exactly 12 'animate-on-twos' steps, NPR_TIME_STEP_MS = 1000/12, and durationMs 4000 is exactly 4 periods), so the frame at t==durationMs matches t==0 at every whimsy. The conductor re-arms at durationMs until the host stops the play handle; amp is a steady gentle periodic breathe of phase (NOT envelope(life)), so there is no one-shot fade to break the seam. Fully declarative — no swift/ or android/ folder; the toolchain generates the Metal + Kotlin factories and shaders from this one .dope plus the single GLSL ES 3.00 source.",
+        "tags": [
+            "loading",
+            "ambient",
+            "continuous",
+            "looping",
+            "thinking"
+        ]
+    },
+    "controls": {
+        "mood": {
+            "type": "enum",
+            "default": "celebratory",
+            "options": [
+                "serene",
+                "celebratory",
+                "electric"
+            ],
+            "ui": "segmented"
+        },
+        "intensity": {
+            "type": "scalar",
+            "default": 0.7,
+            "min": 0,
+            "max": 1,
+            "step": 0.01,
+            "ui": "slider"
+        },
+        "whimsy": {
+            "type": "scalar",
+            "default": 0.5,
+            "min": 0,
+            "max": 1,
+            "step": 0.01,
+            "ui": "slider"
+        },
+        "seed": {
+            "type": "int",
+            "default": null,
+            "nullable": true
+        },
+        "origin": {
+            "type": "point",
+            "default": "center"
+        },
+        "target": {
+            "type": "selector",
+            "default": "document.body"
+        }
+    },
+    "baselines": {
+        "serene": {
+            "durationMs": 4000,
+            "lightness": 0.86,
+            "chroma": 0.08,
+            "hueCenter": 225,
+            "hueRange": 110,
+            "dotCount": 3,
+            "dotRadius": 0.032,
+            "dotGap": 0.11,
+            "breathe": 0.16,
+            "chase": 0.6,
+            "glow": 0.5
+        },
+        "celebratory": {
+            "durationMs": 4000,
+            "lightness": 0.82,
+            "chroma": 0.15,
+            "hueCenter": 200,
+            "hueRange": 280,
+            "dotCount": 4,
+            "dotRadius": 0.03,
+            "dotGap": 0.1,
+            "breathe": 0.2,
+            "chase": 0.85,
+            "glow": 0.65
+        },
+        "electric": {
+            "durationMs": 4000,
+            "lightness": 0.8,
+            "chroma": 0.22,
+            "hueCenter": 195,
+            "hueRange": 160,
+            "dotCount": 5,
+            "dotRadius": 0.026,
+            "dotGap": 0.092,
+            "breathe": 0.24,
+            "chase": 1.1,
+            "glow": 0.9
+        }
+    },
+    "palette": {
+        "model": "oklch",
+        "space": "linear-srgb",
+        "generator": "golden-angle",
+        "goldenAngleDeg": 137.50776405003785,
+        "stops": 3,
+        "hueSpread": 0.55,
+        "lightness": {
+            "baseline": "lightness",
+            "perStop": [
+                0,
+                0.06,
+                -0.05
+            ]
+        },
+        "chroma": {
+            "from": {
+                "mul": [
+                    {
+                        "baseline": "chroma"
+                    },
+                    {
+                        "lerp": [
+                            "intensity",
+                            0.7,
+                            1.5
+                        ]
+                    }
+                ]
+            },
+            "perStop": [
+                0,
+                0.02,
+                -0.01
+            ]
+        },
+        "seed": {
+            "deterministic": true,
+            "source": "controls.seed",
+            "prng": "mulberry32"
+        },
+        "perMood": {
+            "serene": {
+                "hueCenter": 225,
+                "hueRange": 110,
+                "lightness": 0.86,
+                "chroma": 0.08
+            },
+            "celebratory": {
+                "hueCenter": 200,
+                "hueRange": 280,
+                "lightness": 0.82,
+                "chroma": 0.15
+            },
+            "electric": {
+                "hueCenter": 195,
+                "hueRange": 160,
+                "lightness": 0.8,
+                "chroma": 0.22
+            }
+        }
+    },
+    "tempo": {
+        "durationMs": {
+            "from": {
+                "baseline": "durationMs"
+            }
+        },
+        "loop": {
+            "periodMs": 1000
+        },
+        "frame": {
+            "amp": {
+                "add": [
+                    0.85,
+                    {
+                        "mul": [
+                            0.15,
+                            {
+                                "sin": {
+                                    "mul": [
+                                        6.283185307179586,
+                                        {
+                                            "input": "phase"
+                                        }
+                                    ]
+                                }
+                            }
+                        ]
+                    }
+                ]
+            },
+            "extras": {}
+        },
+        "reducedMotion": {
+            "peakMs": 0,
+            "holdMs": 600
+        }
+    },
+    "render": {
+        "params": {
+            "exposure": {
+                "type": "float",
+                "from": {
+                    "lerp": [
+                        "intensity",
+                        0.7,
+                        1.45
+                    ]
+                }
+            },
+            "dotCount": {
+                "type": "int",
+                "from": {
+                    "round": {
+                        "baseline": "dotCount"
+                    }
+                },
+                "clampMax": "MAX_DOTS",
+                "clampMin": "MIN_DOTS"
+            },
+            "dotRadius": {
+                "type": "float",
+                "from": {
+                    "mul": [
+                        {
+                            "baseline": "dotRadius"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                1.2,
+                                0.82
+                            ]
+                        }
+                    ]
+                }
+            },
+            "dotGap": {
+                "type": "float",
+                "from": {
+                    "baseline": "dotGap"
+                }
+            },
+            "breathe": {
+                "type": "float",
+                "from": {
+                    "baseline": "breathe"
+                }
+            },
+            "chase": {
+                "type": "float",
+                "from": {
+                    "mul": [
+                        {
+                            "baseline": "chase"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                0.8,
+                                1.25
+                            ]
+                        }
+                    ]
+                }
+            },
+            "glow": {
+                "type": "float",
+                "from": {
+                    "mul": [
+                        {
+                            "baseline": "glow"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                0.6,
+                                1.3
+                            ]
+                        }
+                    ]
+                }
+            },
+            "style": {
+                "type": "float",
+                "from": {
+                    "control": "whimsy"
+                }
+            }
+        },
+        "shadowHeightFrac": {
+            "min": [
+                {
+                    "add": [
+                        {
+                            "param": "dotRadius"
+                        },
+                        0.04
+                    ]
+                },
+                1
+            ]
+        },
+        "consts": {
+            "MAX_DOTS": 7,
+            "MIN_DOTS": 2
+        },
+        "config": {
+            "usesOrigin": true
+        },
+        "backends": {
+            "webgl2": {
+                "stage": "fullscreen-triangle",
+                "blend": "screen",
+                "shader": {
+                    "program": "dots"
+                }
+            }
+        },
+        "fallbackOrder": [
+            "webgl2"
+        ]
+    },
+    "binding": {
+        "note": "CROSS-PLATFORM uniform-binding contract; SHIPS in the portable .dope. dotsSeed feeds the seeded palette only (no scatterWeb — the shader reads no seed uniform). dotCount is an integer uniform the shader reads to lay out the row. style is whimsy (set automatically), never a uniform.",
+        "excludeParams": [
+            "style"
+        ],
+        "scatterKey": "dotsSeed",
+        "extras": [],
+        "samplers": []
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Dots (the calm ambient "thinking" indicator) as an `EffectFactory` on the
+ * Dopamine backbone.
+ *
+ * FULLY DATA-DRIVEN: everything that isn't the GLSL lives in dots.dope.json —
+ * the mood→params mapping + OKLCH palette (the loader), AND the per-frame logic:
+ * `tempo.frame` (the steady periodic breathe gate), `render.shadowHeightFrac`
+ * (the dots' outer reach), `render.consts` (MAX_DOTS/MIN_DOTS), `render.config`
+ * and the uniform `binding` contract. `registerDopeEffect` interprets that data
+ * through the generic pass runner; this module is just the dot-row SHADER + the
+ * registration call. No swift/ or android/ folder — those factories + the MSL /
+ * Kotlin shaders are generated from this one .dope plus the GLSL source.
+ *
+ * CONTINUOUS / LOOPING. Dots is Dopamine's second continuous effect (after halo):
+ * it declares the first-class `tempo.loop` contract (`periodMs = 1000`): the
+ * parser validates the seam invariants (the period is exactly 12
+ * "animate-on-twos" steps and `durationMs = 4000` is exactly 4 periods), the
+ * runner derives the standard periodic clocks `uPhase`/`uLoopS` every frame, and
+ * `tempo.frame.amp` is a STEADY periodic breathe of that phase —
+ * `0.85 + 0.15·sin(2π·phase)` — so the frame at `t == durationMs` matches
+ * `t == 0` at every whimsy. The conductor re-arms it at every `durationMs` seam;
+ * the host stops it (and can pause/resume it) via the handle `play()` returns.
+ */
+import { type EffectFactory, type PassParams } from "@dopaminefx/core";
+/** The resolved render params Dots' shader consumes. */
+export interface DotsParams extends PassParams {
+    exposure: number;
+    dotCount: number;
+    dotRadius: number;
+    dotGap: number;
+    breathe: number;
+    chase: number;
+    glow: number;
+    dotsSeed: number;
+}
+export declare const dots: EffectFactory<DotsParams>;
+export default dots;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAiC,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKtG,wDAAwD;AACxD,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,eAAO,MAAM,IAAI,EAGkB,aAAa,CAAC,UAAU,CAAC,CAAC;AAE7D,eAAe,IAAI,CAAC"}