From 041d18e8041a96b7515077fb33b30aefb2e19ba2 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 15:41:25 -0400
Subject: [PATCH 01/15] Add v2 visual-narrative design spec for landing page

---
 ...wsga-landing-v2-visual-narrative-design.md | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 specs/2026-05-29-wsga-landing-v2-visual-narrative-design.md

diff --git a/specs/2026-05-29-wsga-landing-v2-visual-narrative-design.md b/specs/2026-05-29-wsga-landing-v2-visual-narrative-design.md
new file mode 100644
index 0000000..3cd94b8
--- /dev/null
+++ b/specs/2026-05-29-wsga-landing-v2-visual-narrative-design.md
@@ -0,0 +1,100 @@
+# WSGA landing page v2 — richer visual narrative (design spec)
+
+**Date:** 2026-05-29
+**Status:** Approved (brainstorming), pending implementation plan
+**Builds on:** `specs/2026-05-29-wsga-landing-page-design.md` (v1, shipped in PR #48 / branch `feature/landing-page`)
+**Scope:** Evolve the single-canvas hero from one visual idea (M-distributions reweighting) into a **dots-forward, multi-beat evolving stage** that gives every narrative scene its own visual support — and fix the scrub timing so balance is reached at scene 04.
+
+---
+
+## 1. Motivation (two user comments)
+
+1. **Timing (easy):** the `std-diff` minimum currently lands at the very bottom (end of scene 05) because `progress()` maps scroll linearly across the whole 5-scene track. It should reach its minimum exactly as **scene 04 (Balance)** arrives; scene 05 holds.
+2. **Visual storytelling (the substance):** today only the M-distribution reweighting is visual, which serves only scenes 03–04. Scenes 01, 02, 05 ride on text. In particular the **problem** (scene 02) — that subgroup effect differences are confounded by M — is never shown. The fix: a single *evolving stage* where dots are the primary actors and a live **effect-gap (Δ) readout** carries the causal story.
+
+The chosen direction merges two explored options: **C** (dots aligning + reweighting = the *mechanism*) as the visual spine, and **B** (an effect gap Δ = the *problem* and *payoff*) as a compact live readout. They are complementary, not exclusive.
+
+## 2. What stays the same
+
+Generative-ink aesthetic, palette/type, split scene layout (text left / visual right), scroll-scrubbed interaction, `prefers-reduced-motion` + no-JS + mobile fallbacks, single self-contained `docs/index.html`, KaTeX + IBM Plex Mono via CDN, seeded determinism (mulberry32, **seed 42**, N=160 per group), analytic-density IPW weights (mode 2 toward pooled). The existing `WSGA` math object is extended, not replaced.
+
+## 3. The evolving stage — three coordinated elements
+
+The visual area holds three elements, all driven by scroll, all always showing true state (no dead/"recomputing" states):
+
+1. **Dots** — individual units, primary actors. G0 = ink `#1d2433`, G1 = red `#b03a2e`. Dot radius encodes IPW weight.
+2. **Density curves** — the *balance verdict*. Introduced at scene 02 (raw, separated); converge during reweighting. (Reuses the existing KDE display path; KDE is display-only — never used for weights.)
+3. **Effect panel (Δ)** — a compact live mini-chart: a short vertical "effect τ" axis with two markers τ(G0) ink / τ(G1) red and the gap Δ bracketed between them, plus the existing `std-diff in M` number. Both markers and numbers animate continuously.
+
+## 4. Scroll timeline — two phases (replaces single linear `t`)
+
+`progress()` is replaced by a phased mapping over the 5-scene track. Define two scalars derived from scroll position:
+
+- **`align ∈ [0,1]`** — Phase A, spans scene 01 → scene 02. Drives: dot-clouds gathering and aligning onto the M axis (at equal size), and the raw curves fading in. No reweighting.
+- **`t ∈ [0,1]`** — Phase B, spans scene 02 → scene 04. Drives reweighting: dot radii, curve convergence, `std-diff` 0.97→0.04, and Δ 4pp→9pp. Eased.
+
+`t` reaches 1 exactly as scene 04's top reaches the viewport; `t` holds at 1 through scene 05 (satisfies motivation #1). Concretely, anchor `align` to the scene-01→02 scroll span and `t` to the scene-02→04 scroll span, using each scene section's geometry (the existing per-scene `data-t` markers can encode anchor targets, or anchors are computed from section offsets).
+
+Reduced-motion: render the final state — `align=1, t=1` (aligned, balanced, Δ=9pp) — statically, no scroll binding (as v1 did for `t=1`).
+
+## 5. Beat-by-beat
+
+| Scene | Dots | Curves | Effect panel (Δ) | M balance |
+|---|---|---|---|---|
+| **01 setup** | two faint clouds (2D, off-axis) | — | τ(G0), τ(G1) shown; **Δ = 4pp (naïve)** | — |
+| **01→02** | gather + align onto M axis, **equal size** | **fade in** (raw, separated) | Δ = 4pp, flagged **"confounded?"** | `std-diff 0.97` appears |
+| **02→04** | **resize** (reweight, exaggerated) | **slide into coincidence** | τ markers **diverge**, Δ **counts 4→9pp** live | `std-diff` 0.97 → 0.04 live |
+| **04 balance** | balanced, settled | coincident | **Δ′ = 9pp**, labeled *"holding M constant"* | `std-diff 0.04` |
+| **05 caveat** | held + faint **hidden-dimension cue** | held | Δ′ = 9pp, footnote *"…if unobservables balance too"* | held |
+
+**Scene 05 hidden-dimension cue (in scope):** a subtle greyed axis or scatter of pale points the weighting does not touch, visually saying "an unobserved dimension remains" — giving scene 05 its own minimal visual. Keep it quiet (low contrast) so it doesn't compete with the settled balance.
+
+**Dot reweighting must be exaggerated** relative to v1 (user note) so the size change reads clearly during Phase B.
+
+**Visual juxtaposition (the "aha"):** as the M-distributions *converge*, the two τ markers *diverge* — "once the groups are comparable, the real (larger) effect difference emerges."
+
+## 6. Synthetic effects (verified, seed 42, N=160)
+
+Each unit has a per-unit treatment effect `τᵢ = α + β·Gᵢ + γ·Mᵢ`. Subgroup effects are **weighted means of `τᵢ` over the same units and IPW weights that drive the dots**, so Δ is genuinely recomputed from the one weight vector (not asserted). The naïve gap `Δ(t) = β + γ·(M̄₁(t) − M̄₀(t))`: balancing M removes the confound term, so weighted `Δ′ → β`. `γ < 0` means high-M units have smaller effects, so the raw imbalance *masks* the true gap (the Fujiwara "effect grows" story).
+
+**Coefficients (verified to hit targets exactly on seed-42 data):**
+- `α = 0.1895`, `β = 0.0924`, `γ = −0.3340`
+
+**Realized values:**
+- t=0 (raw): τ(G0) = 5.0pp, τ(G1) = 9.0pp, **Δ = 4.0pp**
+- t=1 (weighted): τ(G0) = 2.3pp, τ(G1) = 11.3pp, **Δ = 9.0pp**
+
+Displayed as percentage points (effects, e.g. "+9 pp"). `α` only sets marker height (cancels in Δ); β, γ set the gap story. If the DGP/seed ever changes, re-solve β, γ from the realized raw/weighted M-gaps.
+
+## 7. Math object additions (`WSGA`)
+
+Add to the existing object (alongside `G0,G1,w,kde,wmean,wsd,stdDiff`):
+- effect coefficients `ALPHA, BETA, GAMMA`;
+- `tau(p, g)` → `ALPHA + BETA*g + GAMMA*p.m` (per-unit effect);
+- `tauMean(arr, g, t)` → weighted mean of `tau` over a group at reweighting level `t`;
+- `effectGap(t)` → `tauMean(G1,1,t) − tauMean(G0,0,t)`.
+
+`stdDiff` and `effectGap` both read the same `w(p,t)`.
+
+## 8. Scene copy
+
+Scene 01 gains the Δ-effect framing (it currently is "the setup"). The existing KaTeX equations (scenes 02–04) stay; scene 01 may gain a small `Δ = τ(G=1) − τ(G=0)` accent (the scene-02 equation already states this — keep one, avoid duplication). Exact wording finalizable in implementation; the beat structure and the equation/intuition pairing are fixed.
+
+## 9. Implementation implications
+
+- `progress()` → two-phase `{align, t}` mapping from section geometry.
+- `drawHero` → gains: (a) the Phase-A dot gather/align from 2D clouds to the M axis, (b) the effect panel rendering (τ axis, two markers, Δ bracket + value), (c) exaggerated dot-radius mapping, (d) curves fading in at scene 02, (e) the scene-05 hidden-dimension cue.
+- `WSGA` math gains the effect functions (§7).
+- Node guard (`specs/verify_hero_math.mjs`) extends to assert **both** endpoints: `stdDiff` 0.97→~0.04 **and** `effectGap` ~0.040→~0.090 (tight, deterministic under seed 42).
+- Single file, no build step, all v1 robustness paths preserved.
+
+## 10. Verification
+
+`node specs/verify_hero_math.mjs` → PASS asserting both metrics' endpoints. Headless-Chrome captures at: scene 01 (clouds + Δ=4pp), scene 02 (aligned + raw curves + confounded flag), mid Phase-B (resizing + diverging markers), scene 04 (balanced, std-diff 0.04, Δ=9pp), reduced-motion (final state static). Confirm scene-05 cue renders; mobile layout holds; no-JS shows all scene text; `t`=1 reached at scene 04 (not 05).
+
+## 11. Out of scope (v2)
+
+- Full B "morph" (a separate large effect-chart subsystem) — we chose the lightweight live Δ panel instead.
+- DiD variant of the visualization.
+- Interactive controls (sliders for coefficients/seed).
+- Changing the v1 footer, links, report relocation, or page chrome.

From bbe838a7d6afdd82a4901e0c51c961f836dff84c Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 15:49:46 -0400
Subject: [PATCH 02/15] Add v2 visual-narrative implementation plan

---
 ...9-wsga-landing-v2-visual-narrative-plan.md | 425 ++++++++++++++++++
 1 file changed, 425 insertions(+)
 create mode 100644 specs/2026-05-29-wsga-landing-v2-visual-narrative-plan.md

diff --git a/specs/2026-05-29-wsga-landing-v2-visual-narrative-plan.md b/specs/2026-05-29-wsga-landing-v2-visual-narrative-plan.md
new file mode 100644
index 0000000..11262de
--- /dev/null
+++ b/specs/2026-05-29-wsga-landing-v2-visual-narrative-plan.md
@@ -0,0 +1,425 @@
+# WSGA Landing Page v2 — Visual Narrative Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Evolve the landing page hero into a dots-forward, multi-beat evolving stage with a live effect-gap (Δ) readout, and fix the scrub timing so balance is reached at scene 04.
+
+**Architecture:** Modify the single self-contained `docs/index.html` (merged v1). The single scroll scalar `t` becomes a phased `{align, t, hidden}` mapping anchored to scene `offsetTop`s. The `WSGA` math object gains synthetic per-unit effects and a weighted effect-gap. The canvas renderer is replaced wholesale (it's one tightly-coupled function): Phase A gathers 2D dot-clouds onto the M axis and fades the curves in; Phase B reweights (exaggerated dots, converging curves) while the effect markers diverge and Δ counts 4→9pp; scene 05 adds a faint hidden-dimension cue.
+
+**Tech Stack:** Vanilla JS + Canvas 2D, no build step. KaTeX + IBM Plex Mono via CDN. Node for the math guard. Python `http.server` + headless Google Chrome for verification.
+
+**Branch:** `feature/landing-visual-narrative` (already created off merged `main`; carries the v2 design spec). Spec: `specs/2026-05-29-wsga-landing-v2-visual-narrative-design.md`.
+
+**Verified DGP constants (seed 42, N=160):** `ALPHA=0.1895, BETA=0.0924, GAMMA=-0.3340` → effectGap(0)=0.040 (4pp), effectGap(1)=0.090 (9pp); stdDiff(0)=0.94, stdDiff(1)=0.04.
+
+**Visual-tuning note:** Pixel positions/sizes in the renderer (Task 2) are a functional baseline. Exact placement (effect-panel coordinates, dot sizes, cloud spread) is expected to need a screenshot-review pass — the orchestrator captures headless-Chrome screenshots between tasks and tunes. Subagents verify structure/syntax/guard and that the page renders without console errors; they do NOT judge pixels.
+
+---
+
+## File Structure
+
+- **Modify:** `docs/index.html` — the entire deliverable. Three regions change: the `WSGA` math `<script>` (lines ~134-156), the canvas renderer `<script>` (lines ~157-220), and scene DOM/copy (lines ~63, 72-118).
+- **Modify:** `specs/verify_hero_math.mjs` — extend the guard to assert the effect-gap endpoints too.
+
+No new files. Single-file page is intentional (matches v1 + static Pages hosting).
+
+---
+
+## Task 1: Synthetic effects in `WSGA` math + extended Node guard
+
+**Files:**
+- Modify: `docs/index.html` (the `// ---- WSGA hero math` `<script>`, lines ~135-155)
+- Modify: `specs/verify_hero_math.mjs`
+
+- [ ] **Step 1: Extend the Node guard (the test) first**
+
+Replace the entire contents of `specs/verify_hero_math.mjs` with:
+
+```js
+// Regression guard for the WSGA hero math (seed 42, N=160).
+// Mirrors docs/index.html: IPW balance (std-diff) AND synthetic effect gap Δ.
+// Run with: node specs/verify_hero_math.mjs
+function mulberry32(a){return function(){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;};}
+function dnorm(x,m,s){return Math.exp(-0.5*((x-m)/s)**2)/(s*Math.sqrt(2*Math.PI));}
+const MU0=0.42,MU1=0.58,SD=0.17,N=160,SEED=42;
+const ALPHA=0.1895,BETA=0.0924,GAMMA=-0.3340;
+const rng=mulberry32(SEED);
+function rnorm(m,s){let u=0,v=0;while(!u)u=rng();while(!v)v=rng();return m+s*Math.sqrt(-2*Math.log(u))*Math.cos(2*Math.PI*v);}
+const G0=[],G1=[];
+for(let i=0;i<N;i++)G0.push({m:rnorm(MU0,SD)});
+for(let i=0;i<N;i++)G1.push({m:rnorm(MU1,SD)});
+for(const [arr,g] of [[G0,0],[G1,1]]){
+  for(const p of arr){const f0=dnorm(p.m,MU0,SD),f1=dnorm(p.m,MU1,SD),fp=0.5*(f0+f1);p.tw=fp/(g===0?f0:f1);}
+  const mean=arr.reduce((a,p)=>a+p.tw,0)/arr.length; arr.forEach(p=>p.tw/=mean);
+}
+const w=(p,t)=>1+t*(p.tw-1);
+const wmean=(a,t)=>{let s=0,sw=0;for(const p of a){let x=w(p,t);s+=x*p.m;sw+=x;}return s/sw;};
+const wsd=(a,t)=>{let mu=wmean(a,t),s=0,sw=0;for(const p of a){let x=w(p,t);s+=x*(p.m-mu)**2;sw+=x;}return Math.sqrt(s/sw);};
+const stdDiff=t=>Math.abs(wmean(G1,t)-wmean(G0,t))/Math.sqrt((wsd(G0,t)**2+wsd(G1,t)**2)/2);
+const tau=(p,g)=>ALPHA+BETA*g+GAMMA*p.m;
+const tauMean=(a,g,t)=>{let s=0,sw=0;for(const p of a){let x=w(p,t);s+=x*tau(p,g);sw+=x;}return s/sw;};
+const effectGap=t=>tauMean(G1,1,t)-tauMean(G0,0,t);
+const sd0=stdDiff(0),sd1=stdDiff(1),g0=effectGap(0),g1=effectGap(1);
+console.log('std-diff  raw',sd0.toFixed(3),'wtd',sd1.toFixed(3),' | effect gap  raw',(g0*100).toFixed(1)+'pp','wtd',(g1*100).toFixed(1)+'pp');
+if(sd0<0.90) throw new Error('FAIL std-diff raw ~0.94, got '+sd0.toFixed(3));
+if(sd1>0.08) throw new Error('FAIL std-diff wtd ~0.04, got '+sd1.toFixed(3));
+if(g0<0.035||g0>0.045) throw new Error('FAIL effect gap raw ~0.040, got '+g0.toFixed(3));
+if(g1<0.085||g1>0.095) throw new Error('FAIL effect gap wtd ~0.090, got '+g1.toFixed(3));
+console.log('PASS');
+```
+
+- [ ] **Step 2: Run it to confirm it passes against the contract**
+
+Run: `node specs/verify_hero_math.mjs`
+Expected: prints `std-diff raw 0.941 wtd 0.041 | effect gap raw 4.0pp wtd 9.0pp` then `PASS`.
+
+- [ ] **Step 3: Add the effect functions to the page's `WSGA` object**
+
+In `docs/index.html`, inside the `WSGA = (function(){ ... })()` block, find:
+```js
+  function stdDiff(t){return Math.abs(wmean(G1,t)-wmean(G0,t))/Math.sqrt((wsd(G0,t)**2+wsd(G1,t)**2)/2);}
+  return {G0,G1,w,kde,wmean,wsd,stdDiff};
+```
+Replace it with:
+```js
+  function stdDiff(t){return Math.abs(wmean(G1,t)-wmean(G0,t))/Math.sqrt((wsd(G0,t)**2+wsd(G1,t)**2)/2);}
+  // synthetic per-unit treatment effects: tau_i = ALPHA + BETA*G_i + GAMMA*M_i.
+  // GAMMA<0 => high-M units have smaller effects, so M-imbalance MASKS the true gap.
+  // Subgroup effects are weighted means over the same IPW weights -> Delta recomputes honestly.
+  const ALPHA=0.1895, BETA=0.0924, GAMMA=-0.3340;
+  function tau(p,g){return ALPHA+BETA*g+GAMMA*p.m;}
+  function tauMean(arr,g,t){let s=0,sw=0;for(const p of arr){let wv=w(p,t);s+=wv*tau(p,g);sw+=wv;}return s/sw;}
+  function effectGap(t){return tauMean(G1,1,t)-tauMean(G0,0,t);}
+  return {G0,G1,w,kde,wmean,wsd,stdDiff,ALPHA,BETA,GAMMA,tau,tauMean,effectGap};
+```
+
+- [ ] **Step 4: Verify the embedded object exposes the new API and the numbers match**
+
+Run this one-liner (extracts the WSGA IIFE from the page, evals it under Node, prints values):
+```bash
+node -e 'const fs=require("fs");const h=fs.readFileSync("docs/index.html","utf8");const m=h.match(/const WSGA = \(function\(\)\{[\s\S]*?\}\)\(\);/)[0];eval(m);console.log("keys",Object.keys(WSGA).join(","));console.log("gap0",WSGA.effectGap(0).toFixed(3),"gap1",WSGA.effectGap(1).toFixed(3));'
+```
+Expected: keys include `tau,tauMean,effectGap`; `gap0 0.040 gap1 0.090`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/index.html specs/verify_hero_math.mjs
+git commit -m "Add synthetic effect gap to WSGA math + extend guard"
+```
+
+---
+
+## Task 2: Replace the canvas renderer (phased timeline, dots-forward, effect panel)
+
+Replace the entire `// ---- WSGA hero canvas rendering ----` `<script>` (current lines ~157-220) with the v2 renderer below. This is one coherent unit: phased `{align,t,hidden}` timeline, cloud→axis dot alignment, curves fading in with `align`, exaggerated reweight, the effect panel, and the scene-05 hidden cue.
+
+**Files:**
+- Modify: `docs/index.html` (replace the canvas renderer `<script>`)
+
+- [ ] **Step 1: Replace the renderer script**
+
+Replace the whole block that starts with `<script>` / `// ---- WSGA hero canvas rendering ----` and ends at the matching `</script>` (the one immediately before the `<script>` containing `IntersectionObserver`) with EXACTLY:
+
+```html
+<script>
+// ---- WSGA hero canvas rendering (v2: phased timeline, dots-forward, effect panel) ----
+(function(){
+  const cv=document.getElementById('hero'), ctx=cv.getContext('2d');
+  const REDUCE = window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches;
+  const INK='#1d2433', RED='#b03a2e', MUTED='#9a958a';
+  let W,H,DPR;
+  function resize(){DPR=Math.min(2,devicePixelRatio||1);W=cv.clientWidth;H=cv.clientHeight;cv.width=W*DPR;cv.height=H*DPR;ctx.setTransform(DPR,0,0,DPR,0,0);}
+
+  // stable 2D "cloud" start positions per unit (normalized 0..1), deterministic
+  (function seedClouds(){
+    function mb(a){return function(){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;};}
+    const r=mb(7);
+    for(const [arr,cx] of [[WSGA.G0,0.66],[WSGA.G1,0.83]]){
+      for(const p of arr){ p.cxn=cx+(r()-0.5)*0.12; p.cyn=0.42+(r()-0.5)*0.22; }
+    }
+  })();
+
+  const xs=[];for(let i=0;i<=160;i++)xs.push(i/160);
+  function X(m){
+    if(W<=760){const left=0.10*W,right=0.90*W;return left+m*(right-left);}
+    const left=0.56*W,right=0.95*W;return left+m*(right-left);
+  }
+  const clamp=(x)=>Math.max(0,Math.min(1,x));
+  function ease(x){return x<.5?2*x*x:1-Math.pow(-2*x+2,2)/2;}
+  function lerp(a,b,u){return a+(b-a)*u;}
+
+  window.drawHero=function(p){
+    p=p||{}; const align=clamp(p.align||0), te=ease(clamp(p.t||0)), hidden=clamp(p.hidden||0);
+    ctx.clearRect(0,0,W,H);
+    const baseY=(W<=760?H*0.82:H*0.66), amp=H*0.28;
+
+    // curves (fade in with align; reweight with te)
+    const d0=WSGA.kde(WSGA.G0,te,xs,0.05), d1=WSGA.kde(WSGA.G1,te,xs,0.05);
+    const mx=Math.max(Math.max(...d0),Math.max(...d1))*1.05;
+    if(align>0.01){
+      ctx.globalAlpha=align;
+      const curve=(d,color,fill)=>{
+        ctx.beginPath();ctx.moveTo(X(0),baseY);
+        for(let i=0;i<xs.length;i++)ctx.lineTo(X(xs[i]),baseY-(d[i]/mx)*amp);
+        ctx.lineTo(X(1),baseY);ctx.fillStyle=fill;ctx.fill();
+        ctx.beginPath();
+        for(let i=0;i<xs.length;i++){let yy=baseY-(d[i]/mx)*amp;i?ctx.lineTo(X(xs[i]),yy):ctx.moveTo(X(xs[i]),yy);}
+        ctx.strokeStyle=color;ctx.lineWidth=1.2;ctx.stroke();
+      };
+      curve(d0,INK,'rgba(29,36,51,0.07)');
+      curve(d1,RED,'rgba(176,58,46,0.07)');
+      ctx.globalAlpha=1;
+    }
+
+    // dots: 2D cloud (align=0) -> M-axis lane (align=1); radius by weight (te), exaggerated
+    const dots=(arr,color,grp)=>{
+      for(const p2 of arr){
+        const x=lerp(p2.cxn*W,X(p2.m),align), y=lerp(p2.cyn*H,baseY+10+(grp?9:0),align);
+        const wv=WSGA.w(p2,te); const r=2.2+Math.pow(Math.max(0.05,wv),0.9)*2.7;
+        ctx.globalAlpha=0.5;ctx.beginPath();ctx.arc(x,y,r,0,7);ctx.fillStyle=color;ctx.fill();ctx.globalAlpha=1;
+      }
+    };
+    dots(WSGA.G0,INK,0);dots(WSGA.G1,RED,1);
+
+    // baseline, mean ticks, std-diff readout (fade with align)
+    if(align>0.01){
+      ctx.globalAlpha=align;
+      const tick=(arr,color)=>{let mu=WSGA.wmean(arr,te);ctx.setLineDash([3,3]);ctx.beginPath();ctx.moveTo(X(mu),baseY-amp-6);ctx.lineTo(X(mu),baseY+6);ctx.strokeStyle=color;ctx.lineWidth=1;ctx.stroke();ctx.setLineDash([]);};
+      tick(WSGA.G0,INK);tick(WSGA.G1,RED);
+      ctx.beginPath();ctx.moveTo(X(0),baseY);ctx.lineTo(X(1),baseY);ctx.strokeStyle='rgba(29,36,51,0.25)';ctx.lineWidth=1;ctx.stroke();
+      ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+      ctx.fillText('STD. DIFF IN M',X(0),baseY-amp-26);
+      ctx.fillStyle=INK;ctx.font="24px 'IBM Plex Mono',monospace";
+      ctx.fillText(WSGA.stdDiff(te).toFixed(2),X(0),baseY-amp-3);
+      ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='right';
+      ctx.fillText('M →',X(1),baseY+22);ctx.textAlign='left';
+      ctx.globalAlpha=1;
+    }
+
+    // effect panel (always visible) — vertical tau axis, two markers, Delta bracket
+    const eTop=H*0.10, eBot=H*0.26, eX=X(0), eMark=X(0)+16;
+    const yOf=(tau)=>eBot-(Math.max(0,Math.min(0.14,tau))/0.14)*(eBot-eTop);
+    const tau0=WSGA.tauMean(WSGA.G0,0,te), tau1=WSGA.tauMean(WSGA.G1,1,te), gap=WSGA.effectGap(te);
+    ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+    ctx.fillText('EFFECT GAP Δ',eX,eTop-12);
+    ctx.strokeStyle='rgba(29,36,51,0.3)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(eX,eTop);ctx.lineTo(eX,eBot);ctx.stroke();
+    const marker=(tau,color,lab)=>{const y=yOf(tau);ctx.fillStyle=color;ctx.beginPath();ctx.arc(eMark,y,5,0,7);ctx.fill();
+      ctx.font="10px 'IBM Plex Mono',monospace";ctx.textAlign='left';ctx.fillStyle=color;ctx.fillText(lab+' '+(tau*100).toFixed(1)+'pp',eMark+12,y+3);};
+    const y0=yOf(tau0), y1=yOf(tau1), bx=eMark-12;
+    ctx.strokeStyle='rgba(29,36,51,0.4)';ctx.beginPath();ctx.moveTo(eMark,y0);ctx.lineTo(bx,y0);ctx.lineTo(bx,y1);ctx.lineTo(eMark,y1);ctx.stroke();
+    marker(tau0,INK,'τ(G0)');marker(tau1,RED,'τ(G1)');
+    ctx.fillStyle=INK;ctx.font="15px 'IBM Plex Mono',monospace";ctx.textAlign='right';
+    ctx.fillText('Δ '+(gap*100).toFixed(0)+'pp',bx-6,(y0+y1)/2+5);ctx.textAlign='left';
+    ctx.fillStyle=MUTED;ctx.font="10px 'IBM Plex Mono',monospace";
+    const subl = align<0.99 ? 'effects differ by subgroup'
+               : te<0.05 ? 'but is the gap G, or M?'
+               : te<0.95 ? 'holding M constant…'
+               : 'holding M constant';
+    ctx.fillText(subl,eX,eBot+18);
+
+    // scene-05 hidden-dimension cue
+    if(hidden>0.01){
+      ctx.globalAlpha=0.6*hidden;
+      ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+      ctx.fillText('unobserved U — weighting can’t see this',X(0),baseY+46);
+      ctx.strokeStyle='rgba(115,118,126,0.4)';ctx.setLineDash([2,4]);ctx.beginPath();ctx.moveTo(X(0),baseY+62);ctx.lineTo(X(1),baseY+62);ctx.stroke();ctx.setLineDash([]);
+      ctx.fillStyle='rgba(115,118,126,0.55)';
+      for(let i=0;i<24;i++){const gx=X(0.05+0.9*((i*0.137)%1));ctx.beginPath();ctx.arc(gx,baseY+62,2.5,0,7);ctx.fill();}
+      ctx.globalAlpha=1;
+    }
+  };
+
+  // ---- phased scroll timeline ----
+  const secs=[...document.querySelectorAll('.scene')];
+  function progress(){
+    const y=window.scrollY||window.pageYOffset||0, vh=window.innerHeight;
+    const top=i=>secs[i].offsetTop;
+    const seg=(a,b)=> b>a ? clamp((y-a)/(b-a)) : (y>=a?1:0);
+    return {
+      align: seg(top(0),top(1)),                 // phase A: scene 1 -> 2
+      t:     seg(top(1),top(3)),                 // phase B: scene 2 -> 4 (=1 from scene 4 on)
+      hidden:seg(top(4)-vh*0.6, top(4))          // scene 5 cue
+    };
+  }
+  let ticking=false;
+  function frame(){window.__p=progress();drawHero(window.__p);ticking=false;}
+  function onScroll(){if(ticking)return;ticking=true;requestAnimationFrame(frame);}
+  addEventListener('resize',()=>{resize();drawHero(window.__p||{align:0,t:0,hidden:0});});
+  if(REDUCE){ resize();window.__p={align:1,t:1,hidden:0};drawHero(window.__p); }
+  else { addEventListener('scroll',onScroll,{passive:true});resize();window.__p=progress();drawHero(window.__p); }
+})();
+</script>
+```
+
+- [ ] **Step 2: Syntax-check the new renderer**
+
+Extract the renderer `<script>` body to a temp file and run `node --check`:
+```bash
+node -e 'const fs=require("fs");const h=fs.readFileSync("docs/index.html","utf8");const m=h.match(/\/\/ ---- WSGA hero canvas rendering[\s\S]*?\}\)\(\);/)[0];fs.writeFileSync("/tmp/r.js",m);'
+node --check /tmp/r.js && echo "SYNTAX OK"; rm -f /tmp/r.js
+```
+Expected: `SYNTAX OK`.
+
+- [ ] **Step 3: Confirm structure**
+
+```bash
+grep -c "phased timeline" docs/index.html        # 1
+grep -c "EFFECT GAP" docs/index.html             # 1
+grep -c "seedClouds" docs/index.html             # 1
+grep -c "window.__t" docs/index.html             # 0  (old single-t global gone)
+grep -c "hidden-dimension cue" docs/index.html   # 1
+```
+Expected counts as noted.
+
+- [ ] **Step 4: Render check (headless) — produces an artifact for the orchestrator's visual review**
+
+```bash
+cd docs && python3 -m http.server 8021 >/tmp/s.log 2>&1 &
+SRV=$!; sleep 1.5
+CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+"$CHROME" --headless=new --disable-gpu --virtual-time-budget=4000 --dump-dom "http://localhost:8021/" 2>/dev/null | grep -c "id=\"hero\"" ;  # expect 1
+"$CHROME" --headless=new --disable-gpu --window-size=1440,900 --virtual-time-budget=4000 --screenshot=/tmp/wsga_v2_top.png "http://localhost:8021/" 2>/dev/null
+kill $SRV; ls -la /tmp/wsga_v2_top.png
+```
+Expected: canvas present (1); screenshot file created. (Pixel correctness reviewed by the orchestrator.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/index.html
+git commit -m "Replace hero renderer: phased timeline, dots-forward, effect panel, scene-5 cue"
+```
+
+---
+
+## Task 3: Scene copy + DOM alignment with the new visuals
+
+Bring the scene text in line with the new visuals: scene 01 gains the effect-gap framing; the canvas `aria-label` is updated; the dead `data-t` attributes are removed (they're superseded by the phased timeline reading `offsetTop`). The KaTeX equations stay.
+
+**Files:**
+- Modify: `docs/index.html` (lines ~63, 72-118)
+
+- [ ] **Step 1: Update the canvas aria-label**
+
+Replace:
+```html
+<canvas id="hero" aria-label="Animation: two subgroup distributions over a moderator M, reweighted until they coincide."></canvas>
+```
+with:
+```html
+<canvas id="hero" aria-label="Animation: two subgroups' moderator M is reweighted until balanced; the subgroup effect gap grows from 4 to 9 percentage points once M is held constant."></canvas>
+```
+
+- [ ] **Step 2: Rewrite scene 01 to introduce the effect gap**
+
+Replace the scene-1 `<section>` (currently `data-scene="1"`) block with:
+```html
+  <section class="scene" data-scene="1">
+    <div class="text">
+      <div class="mk">01 · the setup</div>
+      <h2>An effect that differs <span class="ll">by subgroup</span>.</h2>
+      <div class="supp">Estimate the treatment effect in G = 0 and G = 1 and compare: a gap of Δ = 4 pp. Is that gap real?</div>
+    </div>
+    <div class="panel"><div class="plotframe"></div></div>
+  </section>
+```
+
+- [ ] **Step 3: Update scene 04 copy to name the payoff (gap grows)**
+
+Replace the scene-4 `<section>` block with:
+```html
+  <section class="scene" data-scene="4">
+    <div class="text">
+      <div class="mk">04 · balance</div>
+      <div class="eq" data-tex="\text{std.\,diff}(M) \;\longrightarrow\; 0"></div>
+      <h2>Hold M constant, and the true gap <span class="ll">emerges</span>.</h2>
+      <div class="supp">With M balanced across subgroups, the effect gap is no longer masked: Δ′ = 9 pp, attributable to G.</div>
+    </div>
+    <div class="panel"><div class="plotframe"></div></div>
+  </section>
+```
+
+- [ ] **Step 4: Remove dead `data-t` attributes from the other scenes**
+
+In the remaining scene sections, change `<section class="scene" data-scene="2" data-t="0">` → `<section class="scene" data-scene="2">`, and likewise for scenes 3 and 5 (drop the `data-t="..."`). The phased timeline derives anchors from `offsetTop`, not these attributes.
+
+- [ ] **Step 5: Verify copy + structure**
+
+```bash
+cd docs && python3 -m http.server 8022 >/tmp/s.log 2>&1 &
+SRV=$!; sleep 1.5
+curl -s http://localhost:8022/ | grep -c 'class="scene"'         # 5
+curl -s http://localhost:8022/ | grep -c 'data-t='              # 0
+curl -s http://localhost:8022/ | grep -c 'Δ = 4 pp'             # 1
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new --disable-gpu --virtual-time-budget=4000 --dump-dom "http://localhost:8022/" 2>/dev/null | grep -c 'class="katex"'   # 3
+kill $SRV
+```
+Expected: 5 scenes, 0 `data-t`, the `Δ = 4 pp` line present, 3 KaTeX equations still render.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add docs/index.html
+git commit -m "Update scene copy and DOM for effect-gap narrative"
+```
+
+---
+
+## Task 4: Final verification, screenshots, and PR
+
+**Files:** none (verification only), unless fixes are needed.
+
+- [ ] **Step 1: Math guard**
+
+Run: `node specs/verify_hero_math.mjs`
+Expected: `PASS` (std-diff 0.94→0.04, effect gap 4.0pp→9.0pp).
+
+- [ ] **Step 2: Capture the five beats + reduced-motion (headless)**
+
+The phased timeline is scroll-driven, so a static `--screenshot` only captures the top. Use Chrome's DevTools-free approach: scroll via a generated URL is not possible, so capture the top frame and the reduced-motion end-state, and rely on the orchestrator to scroll-capture intermediate beats during review.
+
+```bash
+cd docs && python3 -m http.server 8023 >/tmp/s.log 2>&1 &
+SRV=$!; sleep 1.5
+CH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+"$CH" --headless=new --disable-gpu --window-size=1440,900 --virtual-time-budget=4000 --screenshot=/tmp/wsga_v2_setup.png "http://localhost:8023/" 2>/dev/null
+"$CH" --headless=new --disable-gpu --force-prefers-reduced-motion --window-size=1440,900 --virtual-time-budget=4000 --screenshot=/tmp/wsga_v2_reduced.png "http://localhost:8023/" 2>/dev/null
+kill $SRV; ls -la /tmp/wsga_v2_setup.png /tmp/wsga_v2_reduced.png
+```
+Expected: both PNGs created. Orchestrator reviews: setup frame shows two dot-clouds + effect panel (Δ 4pp); reduced-motion shows balanced state + Δ 9pp. (Intermediate beats — aligned/raw-curves at scene 2, diverging markers mid-scroll, balanced at scene 4 — are confirmed in the orchestrator's scroll-driven review.)
+
+- [ ] **Step 3: Confirm v1 robustness paths still hold**
+
+```bash
+cd docs && python3 -m http.server 8024 >/tmp/s.log 2>&1 &
+SRV=$!; sleep 1.5
+curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8024/                    # 200
+curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8024/simulation-report.html  # 200
+for ph in "by subgroup" "tangled with other moderators" "look like" "emerges" "necessary, not"; do curl -s http://localhost:8024/ | grep -c "$ph"; done   # each >=1
+kill $SRV
+```
+Expected: 200, 200, and each scene phrase present in raw HTML (no-JS baseline intact).
+
+- [ ] **Step 4: Confirm `.Rbuildignore` still excludes docs/ and specs/**
+
+```bash
+grep -E '\^docs\$|\^specs\$' .Rbuildignore   # both present
+```
+
+- [ ] **Step 5: Push branch and open PR**
+
+```bash
+git push -u origin feature/landing-visual-narrative
+gh pr create --base main --head feature/landing-visual-narrative \
+  --title "Landing page v2: visual narrative (dots-forward stage + effect gap)" \
+  --body "Evolves the hero into a dots-forward evolving stage with a live effect-gap readout, and fixes scrub timing so balance lands at scene 04. Docs-only — no package code, no version bump (per rescoped CLAUDE.md rule). Spec: specs/2026-05-29-wsga-landing-v2-visual-narrative-design.md."
+```
+
+---
+
+## Post-implementation notes
+
+- **No version bump:** this PR changes only `docs/` and `specs/` — no R/Stata package code — so under the rescoped versioning rule it needs no bump.
+- **Visual tuning is expected:** effect-panel coordinates, dot sizes, cloud spread, and the scene-05 cue placement may need a screenshot-review pass after Task 2. The orchestrator owns that (subagents verify structure/syntax/render, not pixels).
+- **After merge:** GitHub Pages rebuilds `main`/`docs` automatically; verify `alvarocarril.com/wsga/` shows the v2 hero once the build completes.

From 36c03b24620644919cab98a6d5f32f74f5c46a54 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 15:53:07 -0400
Subject: [PATCH 03/15] Add synthetic effect gap to WSGA math + extend guard

---
 docs/index.html            |  9 ++++++++-
 specs/verify_hero_math.mjs | 22 ++++++++++++++--------
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 872ee89..284ff33 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -151,7 +151,14 @@ <h2>Use it.</h2>
   function wmean(arr,t){let s=0,sw=0;for(const p of arr){let wv=w(p,t);s+=wv*p.m;sw+=wv;}return s/sw;}
   function wsd(arr,t){let mu=wmean(arr,t),s=0,sw=0;for(const p of arr){let wv=w(p,t);s+=wv*(p.m-mu)**2;sw+=wv;}return Math.sqrt(s/sw);}
   function stdDiff(t){return Math.abs(wmean(G1,t)-wmean(G0,t))/Math.sqrt((wsd(G0,t)**2+wsd(G1,t)**2)/2);}
-  return {G0,G1,w,kde,wmean,wsd,stdDiff};
+  // synthetic per-unit treatment effects: tau_i = ALPHA + BETA*G_i + GAMMA*M_i.
+  // GAMMA<0 => high-M units have smaller effects, so M-imbalance MASKS the true gap.
+  // Subgroup effects are weighted means over the same IPW weights -> the gap recomputes honestly.
+  const ALPHA=0.1895, BETA=0.0924, GAMMA=-0.3340;
+  function tau(p,g){return ALPHA+BETA*g+GAMMA*p.m;}
+  function tauMean(arr,g,t){let s=0,sw=0;for(const p of arr){let wv=w(p,t);s+=wv*tau(p,g);sw+=wv;}return s/sw;}
+  function effectGap(t){return tauMean(G1,1,t)-tauMean(G0,0,t);}
+  return {G0,G1,w,kde,wmean,wsd,stdDiff,ALPHA,BETA,GAMMA,tau,tauMean,effectGap};
 })();
 </script>
 <script>
diff --git a/specs/verify_hero_math.mjs b/specs/verify_hero_math.mjs
index f7880fe..ff36693 100644
--- a/specs/verify_hero_math.mjs
+++ b/specs/verify_hero_math.mjs
@@ -1,9 +1,10 @@
-// Regression guard for the WSGA hero IPW math.
-// Mirrors the SEEDED algorithm in docs/index.html (seed 42, N=160) so it tests
-// the exact instance the page renders. Run with: node specs/verify_hero_math.mjs
+// Regression guard for the WSGA hero math (seed 42, N=160).
+// Mirrors docs/index.html: IPW balance (std-diff) AND synthetic effect gap (Delta).
+// Run with: node specs/verify_hero_math.mjs
 function mulberry32(a){return function(){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;};}
 function dnorm(x,m,s){return Math.exp(-0.5*((x-m)/s)**2)/(s*Math.sqrt(2*Math.PI));}
 const MU0=0.42,MU1=0.58,SD=0.17,N=160,SEED=42;
+const ALPHA=0.1895,BETA=0.0924,GAMMA=-0.3340;
 const rng=mulberry32(SEED);
 function rnorm(m,s){let u=0,v=0;while(!u)u=rng();while(!v)v=rng();return m+s*Math.sqrt(-2*Math.log(u))*Math.cos(2*Math.PI*v);}
 const G0=[],G1=[];
@@ -16,9 +17,14 @@ for(const [arr,g] of [[G0,0],[G1,1]]){
 const w=(p,t)=>1+t*(p.tw-1);
 const wmean=(a,t)=>{let s=0,sw=0;for(const p of a){let x=w(p,t);s+=x*p.m;sw+=x;}return s/sw;};
 const wsd=(a,t)=>{let mu=wmean(a,t),s=0,sw=0;for(const p of a){let x=w(p,t);s+=x*(p.m-mu)**2;sw+=x;}return Math.sqrt(s/sw);};
-const sd=t=>Math.abs(wmean(G1,t)-wmean(G0,t))/Math.sqrt((wsd(G0,t)**2+wsd(G1,t)**2)/2);
-const raw=sd(0), wtd=sd(1);
-console.log('seed',SEED,'unweighted std-diff:',raw.toFixed(3),' weighted std-diff:',wtd.toFixed(3));
-if(raw < 0.90) throw new Error('FAIL: unweighted std-diff should be ~0.94, got '+raw.toFixed(3));
-if(wtd > 0.08) throw new Error('FAIL: weighted std-diff should collapse to ~0.04, got '+wtd.toFixed(3));
+const stdDiff=t=>Math.abs(wmean(G1,t)-wmean(G0,t))/Math.sqrt((wsd(G0,t)**2+wsd(G1,t)**2)/2);
+const tau=(p,g)=>ALPHA+BETA*g+GAMMA*p.m;
+const tauMean=(a,g,t)=>{let s=0,sw=0;for(const p of a){let x=w(p,t);s+=x*tau(p,g);sw+=x;}return s/sw;};
+const effectGap=t=>tauMean(G1,1,t)-tauMean(G0,0,t);
+const sd0=stdDiff(0),sd1=stdDiff(1),g0=effectGap(0),g1=effectGap(1);
+console.log('std-diff  raw',sd0.toFixed(3),'wtd',sd1.toFixed(3),' | effect gap  raw',(g0*100).toFixed(1)+'pp','wtd',(g1*100).toFixed(1)+'pp');
+if(sd0<0.90) throw new Error('FAIL std-diff raw ~0.94, got '+sd0.toFixed(3));
+if(sd1>0.08) throw new Error('FAIL std-diff wtd ~0.04, got '+sd1.toFixed(3));
+if(g0<0.035||g0>0.045) throw new Error('FAIL effect gap raw ~0.040, got '+g0.toFixed(3));
+if(g1<0.085||g1>0.095) throw new Error('FAIL effect gap wtd ~0.090, got '+g1.toFixed(3));
 console.log('PASS');

From 3ce108d563f6d4b20cc955a94b535a9bad397c36 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 16:08:08 -0400
Subject: [PATCH 04/15] Replace hero renderer: phased timeline, dots-forward,
 effect panel, scene-5 cue

---
 docs/index.html | 144 ++++++++++++++++++++++++++++++++++--------------
 1 file changed, 104 insertions(+), 40 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 284ff33..5a3bd7f 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -162,67 +162,131 @@ <h2>Use it.</h2>
 })();
 </script>
 <script>
-// ---- WSGA hero canvas rendering ----
+// ---- WSGA hero canvas rendering (v2: phased timeline, dots-forward, effect panel) ----
 (function(){
   const cv=document.getElementById('hero'), ctx=cv.getContext('2d');
   const REDUCE = window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches;
-  const INK='#1d2433', RED='#b03a2e';
+  const INK='#1d2433', RED='#b03a2e', MUTED='#9a958a';
   let W,H,DPR;
   function resize(){DPR=Math.min(2,devicePixelRatio||1);W=cv.clientWidth;H=cv.clientHeight;cv.width=W*DPR;cv.height=H*DPR;ctx.setTransform(DPR,0,0,DPR,0,0);}
-  addEventListener('resize',()=>{resize();drawHero(window.__t||0);});
 
-  // plot occupies the right ~42% of the viewport, vertically centered band
+  // stable 2D "cloud" start positions per unit (normalized 0..1), deterministic
+  (function seedClouds(){
+    function mb(a){return function(){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;};}
+    const r=mb(7);
+    for(const [arr,cx] of [[WSGA.G0,0.66],[WSGA.G1,0.83]]){
+      for(const p of arr){ p.cxn=cx+(r()-0.5)*0.12; p.cyn=0.60+(r()-0.5)*0.16; }
+    }
+  })();
+
   const xs=[];for(let i=0;i<=160;i++)xs.push(i/160);
   function X(m){
     if(W<=760){const left=0.10*W,right=0.90*W;return left+m*(right-left);}
     const left=0.56*W,right=0.95*W;return left+m*(right-left);
   }
+  const clamp=(x)=>Math.max(0,Math.min(1,x));
   function ease(x){return x<.5?2*x*x:1-Math.pow(-2*x+2,2)/2;}
+  function lerp(a,b,u){return a+(b-a)*u;}
 
-  window.drawHero=function(raw){
-    const t=ease(Math.max(0,Math.min(1,raw)));
+  window.drawHero=function(p){
+    p=p||{}; const align=clamp(p.align||0), te=ease(clamp(p.t||0)), hidden=clamp(p.hidden||0);
     ctx.clearRect(0,0,W,H);
-    const baseY = (W<=760 ? H*0.84 : H*0.66), amp=H*0.30;
-    const d0=WSGA.kde(WSGA.G0,t,xs,0.05), d1=WSGA.kde(WSGA.G1,t,xs,0.05);
+    const baseY=(W<=760?H*0.78:H*0.70), amp=H*0.18;
+
+    // curves (fade in with align; reweight with te)
+    const d0=WSGA.kde(WSGA.G0,te,xs,0.05), d1=WSGA.kde(WSGA.G1,te,xs,0.05);
     const mx=Math.max(Math.max(...d0),Math.max(...d1))*1.05;
-    function curve(d,color,fill){
-      ctx.beginPath();ctx.moveTo(X(0),baseY);
-      for(let i=0;i<xs.length;i++)ctx.lineTo(X(xs[i]),baseY-(d[i]/mx)*amp);
-      ctx.lineTo(X(1),baseY);ctx.fillStyle=fill;ctx.fill();
-      ctx.beginPath();
-      for(let i=0;i<xs.length;i++){let yy=baseY-(d[i]/mx)*amp;i?ctx.lineTo(X(xs[i]),yy):ctx.moveTo(X(xs[i]),yy);}
-      ctx.strokeStyle=color;ctx.lineWidth=1.2;ctx.stroke();
+    if(align>0.01){
+      ctx.globalAlpha=align;
+      const curve=(d,color,fill)=>{
+        ctx.beginPath();ctx.moveTo(X(0),baseY);
+        for(let i=0;i<xs.length;i++)ctx.lineTo(X(xs[i]),baseY-(d[i]/mx)*amp);
+        ctx.lineTo(X(1),baseY);ctx.fillStyle=fill;ctx.fill();
+        ctx.beginPath();
+        for(let i=0;i<xs.length;i++){let yy=baseY-(d[i]/mx)*amp;i?ctx.lineTo(X(xs[i]),yy):ctx.moveTo(X(xs[i]),yy);}
+        ctx.strokeStyle=color;ctx.lineWidth=1.2;ctx.stroke();
+      };
+      curve(d0,INK,'rgba(29,36,51,0.07)');
+      curve(d1,RED,'rgba(176,58,46,0.07)');
+      ctx.globalAlpha=1;
     }
-    curve(d0,INK,'rgba(29,36,51,0.07)');
-    curve(d1,RED,'rgba(176,58,46,0.07)');
-    function dots(arr,color,grp){for(const p of arr){let wv=WSGA.w(p,t);let r=1.4+Math.sqrt(Math.max(0.05,wv))*1.7;ctx.globalAlpha=0.5;ctx.beginPath();ctx.arc(X(p.m),baseY+10+(grp?9:0),r,0,7);ctx.fillStyle=color;ctx.fill();ctx.globalAlpha=1;}}
+
+    // dots: 2D cloud (align=0) -> M-axis lane (align=1); radius by weight (te), exaggerated
+    const dots=(arr,color,grp)=>{
+      for(const p2 of arr){
+        const x=lerp(p2.cxn*W,X(p2.m),align), y=lerp(p2.cyn*H,baseY+10+(grp?9:0),align);
+        const wv=WSGA.w(p2,te); const r=2.2+Math.pow(Math.max(0.05,wv),0.9)*2.7;
+        ctx.globalAlpha=0.5;ctx.beginPath();ctx.arc(x,y,r,0,7);ctx.fillStyle=color;ctx.fill();ctx.globalAlpha=1;
+      }
+    };
     dots(WSGA.G0,INK,0);dots(WSGA.G1,RED,1);
-    function tick(arr,color){let mu=WSGA.wmean(arr,t);ctx.setLineDash([3,3]);ctx.beginPath();ctx.moveTo(X(mu),baseY-amp-6);ctx.lineTo(X(mu),baseY+6);ctx.strokeStyle=color;ctx.lineWidth=1;ctx.stroke();ctx.setLineDash([]);}
-    tick(WSGA.G0,INK);tick(WSGA.G1,RED);
-    ctx.beginPath();ctx.moveTo(X(0),baseY);ctx.lineTo(X(1),baseY);ctx.strokeStyle='rgba(29,36,51,0.25)';ctx.lineWidth=1;ctx.stroke();
-    // readout
-    ctx.fillStyle='#9a958a';ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
-    ctx.fillText('STD. DIFF IN M',X(0),baseY-amp-26);
-    ctx.fillStyle=INK;ctx.font="26px 'IBM Plex Mono',monospace";
-    ctx.fillText(WSGA.stdDiff(t).toFixed(2),X(0),baseY-amp-2);
-    ctx.fillStyle='#9a958a';ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='right';
-    ctx.fillText('M →',X(1),baseY+22);ctx.textAlign='left';
+
+    // baseline, mean ticks, std-diff readout (fade with align)
+    if(align>0.01){
+      ctx.globalAlpha=align;
+      const tick=(arr,color)=>{let mu=WSGA.wmean(arr,te);ctx.setLineDash([3,3]);ctx.beginPath();ctx.moveTo(X(mu),baseY-amp-6);ctx.lineTo(X(mu),baseY+6);ctx.strokeStyle=color;ctx.lineWidth=1;ctx.stroke();ctx.setLineDash([]);};
+      tick(WSGA.G0,INK);tick(WSGA.G1,RED);
+      ctx.beginPath();ctx.moveTo(X(0),baseY);ctx.lineTo(X(1),baseY);ctx.strokeStyle='rgba(29,36,51,0.25)';ctx.lineWidth=1;ctx.stroke();
+      ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+      ctx.fillText('STD. DIFF IN M',X(0),baseY+42);
+      ctx.fillStyle=INK;ctx.font="24px 'IBM Plex Mono',monospace";
+      ctx.fillText(WSGA.stdDiff(te).toFixed(2),X(0),baseY+68);
+      ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='right';
+      ctx.fillText('M →',X(1),baseY+22);ctx.textAlign='left';
+      ctx.globalAlpha=1;
+    }
+
+    // effect panel (always visible) -- vertical tau axis, two markers, Delta bracket
+    const eTop=H*0.36, eBot=H*0.50, eX=X(0), eMark=X(0)+16;
+    const yOf=(tau)=>eBot-(Math.max(0,Math.min(0.14,tau))/0.14)*(eBot-eTop);
+    const tau0=WSGA.tauMean(WSGA.G0,0,te), tau1=WSGA.tauMean(WSGA.G1,1,te), gap=WSGA.effectGap(te);
+    ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+    ctx.fillText('EFFECT GAP Δ',eX,eTop-12);
+    ctx.strokeStyle='rgba(29,36,51,0.3)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(eX,eTop);ctx.lineTo(eX,eBot);ctx.stroke();
+    const marker=(tau,color,lab)=>{const y=yOf(tau);ctx.fillStyle=color;ctx.beginPath();ctx.arc(eMark,y,5,0,7);ctx.fill();
+      ctx.font="10px 'IBM Plex Mono',monospace";ctx.textAlign='left';ctx.fillStyle=color;ctx.fillText(lab+' '+(tau*100).toFixed(1)+'pp',eMark+12,y+3);};
+    const y0=yOf(tau0), y1=yOf(tau1), bx=eMark-12;
+    ctx.strokeStyle='rgba(29,36,51,0.4)';ctx.beginPath();ctx.moveTo(eMark,y0);ctx.lineTo(bx,y0);ctx.lineTo(bx,y1);ctx.lineTo(eMark,y1);ctx.stroke();
+    marker(tau0,INK,'τ(G0)');marker(tau1,RED,'τ(G1)');
+    ctx.fillStyle=INK;ctx.font="15px 'IBM Plex Mono',monospace";ctx.textAlign='right';
+    ctx.fillText('Δ '+(gap*100).toFixed(0)+'pp',bx-6,(y0+y1)/2+5);ctx.textAlign='left';
+    ctx.fillStyle=MUTED;ctx.font="10px 'IBM Plex Mono',monospace";
+    const subl = align<0.99 ? 'effects differ by subgroup'
+               : te<0.05 ? 'but is the gap G, or M?'
+               : te<0.95 ? 'holding M constant…'
+               : 'holding M constant';
+    ctx.fillText(subl,eX,eBot+18);
+
+    // scene-05 hidden-dimension cue
+    if(hidden>0.01){
+      ctx.globalAlpha=0.6*hidden;
+      ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+      ctx.fillText('unobserved U — weighting can’t see this',X(0),baseY+94);
+      ctx.strokeStyle='rgba(115,118,126,0.4)';ctx.setLineDash([2,4]);ctx.beginPath();ctx.moveTo(X(0),baseY+110);ctx.lineTo(X(1),baseY+110);ctx.stroke();ctx.setLineDash([]);
+      ctx.fillStyle='rgba(115,118,126,0.55)';
+      for(let i=0;i<24;i++){const gx=X(0.05+0.9*((i*0.137)%1));ctx.beginPath();ctx.arc(gx,baseY+110,2.5,0,7);ctx.fill();}
+      ctx.globalAlpha=1;
+    }
   };
 
-  const track=document.getElementById('track');
-  let ticking=false;
+  // ---- phased scroll timeline ----
+  const secs=[...document.querySelectorAll('.scene')];
   function progress(){
-    const r=track.getBoundingClientRect();
-    const total=r.height-window.innerHeight;          // scrollable distance within the track
-    const scrolled=Math.min(Math.max(-r.top,0),total);
-    return total>0 ? scrolled/total : 0;
-  }
-  function onScroll(){
-    if(ticking)return;ticking=true;
-    requestAnimationFrame(()=>{window.__t=progress();drawHero(window.__t);ticking=false;});
+    const y=window.scrollY||window.pageYOffset||0, vh=window.innerHeight;
+    const top=i=>secs[i].offsetTop;
+    const seg=(a,b)=> b>a ? clamp((y-a)/(b-a)) : (y>=a?1:0);
+    return {
+      align: seg(top(0),top(1)),                 // phase A: scene 1 -> 2
+      t:     seg(top(1),top(3)),                 // phase B: scene 2 -> 4 (=1 from scene 4 on)
+      hidden:seg(top(4)-vh*0.6, top(4))          // scene 5 cue
+    };
   }
-  if(REDUCE){ resize();window.__t=1;drawHero(1); }
-  else { addEventListener('scroll',onScroll,{passive:true});resize();window.__t=progress();drawHero(window.__t); }
+  let ticking=false;
+  function frame(){window.__p=progress();drawHero(window.__p);ticking=false;}
+  function onScroll(){if(ticking)return;ticking=true;requestAnimationFrame(frame);}
+  addEventListener('resize',()=>{resize();drawHero(window.__p||{align:0,t:0,hidden:0});});
+  if(REDUCE){ resize();window.__p={align:1,t:1,hidden:0};drawHero(window.__p); }
+  else { addEventListener('scroll',onScroll,{passive:true});resize();window.__p=progress();drawHero(window.__p); }
 })();
 </script>
 <script>

From c4e2f0f6881dff8ea5ca01d233dbbb968ab9b546 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 16:09:43 -0400
Subject: [PATCH 05/15] Update scene copy and DOM for effect-gap narrative

---
 docs/index.html | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 5a3bd7f..832f968 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -60,7 +60,7 @@
 </style>
 </head>
 <body>
-<canvas id="hero" aria-label="Animation: two subgroup distributions over a moderator M, reweighted until they coincide."></canvas>
+<canvas id="hero" aria-label="Animation: two subgroups' moderator M is reweighted until balanced; the subgroup effect gap grows from 4 to 9 percentage points once M is held constant."></canvas>
 <header class="site">
   <div class="kicker">Weighted Subgroup Analysis</div>
   <h1>Two subgroups,<br>pulled into <em>balance</em>.</h1>
@@ -69,16 +69,16 @@ <h1>Two subgroups,<br>pulled into <em>balance</em>.</h1>
 
 <main id="track">
 
-  <section class="scene" data-scene="1" data-t="0">
+  <section class="scene" data-scene="1">
     <div class="text">
       <div class="mk">01 · the setup</div>
-      <h2>Many studies ask how an effect differs <span class="ll">by subgroup</span>.</h2>
-      <div class="supp">Split the sample into G = 0 and G = 1, estimate the treatment effect in each, and compare.</div>
+      <h2>An effect that differs <span class="ll">by subgroup</span>.</h2>
+      <div class="supp">Estimate the treatment effect in G = 0 and G = 1 and compare: a gap of Δ = 4 pp. Is that gap real?</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
   </section>
 
-  <section class="scene" data-scene="2" data-t="0">
+  <section class="scene" data-scene="2">
     <div class="text">
       <div class="mk">02 · the problem</div>
       <div class="eq" data-tex="\Delta \;=\; \tau(G{=}1) \;-\; \tau(G{=}0)"></div>
@@ -88,7 +88,7 @@ <h2>But G is tangled with other moderators M.</h2>
     <div class="panel"><div class="plotframe"></div></div>
   </section>
 
-  <section class="scene" data-scene="3" data-t="0.6">
+  <section class="scene" data-scene="3">
     <div class="text">
       <div class="mk">03 · the idea</div>
       <div class="eq" data-tex="w_i \;=\; \hat f_{\text{pool}}(M_i) \,/\, \hat f_{G(i)}(M_i)"></div>
@@ -98,17 +98,17 @@ <h2>Up-weight the units that <span class="ll">look like</span> the other group.<
     <div class="panel"><div class="plotframe"></div></div>
   </section>
 
-  <section class="scene" data-scene="4" data-t="1">
+  <section class="scene" data-scene="4">
     <div class="text">
       <div class="mk">04 · balance</div>
       <div class="eq" data-tex="\text{std.\,diff}(M) \;\longrightarrow\; 0"></div>
-      <h2>Now M is distributed <span class="ll">identically</span> across subgroups.</h2>
-      <div class="supp">The remaining difference in effects is attributable to G, holding M constant.</div>
+      <h2>Hold M constant, and the true gap <span class="ll">emerges</span>.</h2>
+      <div class="supp">With M balanced across subgroups, the effect gap is no longer masked: Δ&prime; = 9 pp, attributable to G.</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
   </section>
 
-  <section class="scene" data-scene="5" data-t="1">
+  <section class="scene" data-scene="5">
     <div class="text">
       <div class="mk">05 · the honest caveat</div>
       <h2>Observable balance is necessary, not <span class="ll">sufficient</span>.</h2>

From 3c49c175cf7dc6a6834f0ad6f25a06f4a4ea9e60 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 16:41:47 -0400
Subject: [PATCH 06/15] Rework scene 1: effect-height dot bands + explicit
 Delta bracket; clarify framing/copy

---
 docs/index.html | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 832f968..5f69837 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -72,8 +72,8 @@ <h1>Two subgroups,<br>pulled into <em>balance</em>.</h1>
   <section class="scene" data-scene="1">
     <div class="text">
       <div class="mk">01 · the setup</div>
-      <h2>An effect that differs <span class="ll">by subgroup</span>.</h2>
-      <div class="supp">Estimate the treatment effect in G = 0 and G = 1 and compare: a gap of Δ = 4 pp. Is that gap real?</div>
+      <h2>Comparing an effect <span class="ll">across subgroups</span>.</h2>
+      <div class="supp">Estimate the treatment effect within G = 0 and within G = 1, then compare them — a gap of Δ = 4 pp. Should we trust it?</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
   </section>
@@ -174,8 +174,9 @@ <h2>Use it.</h2>
   (function seedClouds(){
     function mb(a){return function(){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;};}
     const r=mb(7);
-    for(const [arr,cx] of [[WSGA.G0,0.66],[WSGA.G1,0.83]]){
-      for(const p of arr){ p.cxn=cx+(r()-0.5)*0.12; p.cyn=0.60+(r()-0.5)*0.16; }
+    // two horizontal bands at effect heights: G1 (bigger effect) upper, G0 lower
+    for(const [arr,cy] of [[WSGA.G0,0.60],[WSGA.G1,0.42]]){
+      for(const p of arr){ p.cxn=0.61+r()*0.30; p.cyn=cy+(r()-0.5)*0.09; }
     }
   })();
 
@@ -236,7 +237,9 @@ <h2>Use it.</h2>
       ctx.globalAlpha=1;
     }
 
-    // effect panel (always visible) -- vertical tau axis, two markers, Delta bracket
+    // effect panel (fades in with align; carries tau + Delta from scene 2 on)
+    if(align>0.01){
+    ctx.globalAlpha=align;
     const eTop=H*0.36, eBot=H*0.50, eX=X(0), eMark=X(0)+16;
     const yOf=(tau)=>eBot-(Math.max(0,Math.min(0.14,tau))/0.14)*(eBot-eTop);
     const tau0=WSGA.tauMean(WSGA.G0,0,te), tau1=WSGA.tauMean(WSGA.G1,1,te), gap=WSGA.effectGap(te);
@@ -251,11 +254,28 @@ <h2>Use it.</h2>
     ctx.fillStyle=INK;ctx.font="15px 'IBM Plex Mono',monospace";ctx.textAlign='right';
     ctx.fillText('Δ '+(gap*100).toFixed(0)+'pp',bx-6,(y0+y1)/2+5);ctx.textAlign='left';
     ctx.fillStyle=MUTED;ctx.font="10px 'IBM Plex Mono',monospace";
-    const subl = align<0.99 ? 'effects differ by subgroup'
+    const subl = align<0.99 ? 'comparing subgroup effects'
                : te<0.05 ? 'but is the gap G, or M?'
                : te<0.95 ? 'holding M constant…'
                : 'holding M constant';
     ctx.fillText(subl,eX,eBot+18);
+    ctx.globalAlpha=1;
+    }
+
+    // scene-1 explicit effect-gap bracket between the two dot bands (fades out as dots align)
+    if(align<0.99){
+      ctx.globalAlpha=1-align;
+      const yG1=H*0.42, yG0=H*0.60, xBr=W*0.585;
+      ctx.fillStyle=MUTED;ctx.font="10px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+      ctx.fillText('EFFECT GAP',xBr-2,yG1-H*0.10);
+      ctx.font="11px 'IBM Plex Mono',monospace";
+      ctx.fillStyle=RED;ctx.fillText('G = 1',W*0.925,yG1+4);
+      ctx.fillStyle=INK;ctx.fillText('G = 0',W*0.925,yG0+4);
+      ctx.strokeStyle='rgba(29,36,51,0.45)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(xBr+10,yG1);ctx.lineTo(xBr,yG1);ctx.lineTo(xBr,yG0);ctx.lineTo(xBr+10,yG0);ctx.stroke();
+      ctx.fillStyle=INK;ctx.font="16px 'IBM Plex Mono',monospace";ctx.textAlign='right';
+      ctx.fillText('Δ '+(WSGA.effectGap(te)*100).toFixed(0)+'pp',xBr-8,(yG1+yG0)/2+5);
+      ctx.textAlign='left';ctx.globalAlpha=1;
+    }
 
     // scene-05 hidden-dimension cue
     if(hidden>0.01){

From 9bf27754ffea11c38f99484f3c391c0b77628947 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 16:54:35 -0400
Subject: [PATCH 07/15] Text fixes: move Delta def to scene 1, M-formula +
 math-mode G/M in scene 2, copy tweaks

---
 docs/index.html | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 5f69837..92922c5 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -72,8 +72,9 @@ <h1>Two subgroups,<br>pulled into <em>balance</em>.</h1>
   <section class="scene" data-scene="1">
     <div class="text">
       <div class="mk">01 · the setup</div>
+      <div class="eq" data-tex="\Delta \;=\; \tau(G{=}1) \;-\; \tau(G{=}0)"></div>
       <h2>Comparing an effect <span class="ll">across subgroups</span>.</h2>
-      <div class="supp">Estimate the treatment effect within G = 0 and within G = 1, then compare them — a gap of Δ = 4 pp. Should we trust it?</div>
+      <div class="supp">Estimate the treatment effect within subgroup G = 0 and within subgroup G = 1, then compare them. A gap of Δ = 4 pp. Should we trust it?</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
   </section>
@@ -81,8 +82,8 @@ <h2>Comparing an effect <span class="ll">across subgroups</span>.</h2>
   <section class="scene" data-scene="2">
     <div class="text">
       <div class="mk">02 · the problem</div>
-      <div class="eq" data-tex="\Delta \;=\; \tau(G{=}1) \;-\; \tau(G{=}0)"></div>
-      <h2>But G is tangled with other moderators M.</h2>
+      <div class="eq" data-tex="\mathbb{E}[M \mid G{=}1] \;\neq\; \mathbb{E}[M \mid G{=}0]"></div>
+      <h2><span data-tex="G"></span> is tangled with other moderators <span data-tex="M"></span>.</h2>
       <div class="supp">Is the effect different by G — or by what G is <em>correlated with</em>? The subgroups don't share the same distribution of M.</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
@@ -102,7 +103,7 @@ <h2>Up-weight the units that <span class="ll">look like</span> the other group.<
     <div class="text">
       <div class="mk">04 · balance</div>
       <div class="eq" data-tex="\text{std.\,diff}(M) \;\longrightarrow\; 0"></div>
-      <h2>Hold M constant, and the true gap <span class="ll">emerges</span>.</h2>
+      <h2>Hold <span data-tex="M"></span> constant, and the true gap <span class="ll">emerges</span>.</h2>
       <div class="supp">With M balanced across subgroups, the effect gap is no longer masked: Δ&prime; = 9 pp, attributable to G.</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
@@ -322,7 +323,7 @@ <h2>Use it.</h2>
   // KaTeX render of inline equations (defer-loaded; run on load)
   window.addEventListener('load',function(){
     if(!window.katex)return;
-    document.querySelectorAll('.eq[data-tex]').forEach(function(el){
+    document.querySelectorAll('[data-tex]').forEach(function(el){
       try{katex.render(el.getAttribute('data-tex'),el,{throwOnError:false,displayMode:false});}catch(e){el.textContent=el.getAttribute('data-tex');}
     });
   });

From 366c50e4d7bd28e1c58ba674c8392e3628f36de1 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 17:01:38 -0400
Subject: [PATCH 08/15] Morph effect-gap bracket from scene-1 band gap into
 scene-2 panel (no cross-fade)

---
 docs/index.html | 74 +++++++++++++++++++++++++------------------------
 1 file changed, 38 insertions(+), 36 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 92922c5..48cadb7 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -238,44 +238,46 @@ <h2>Use it.</h2>
       ctx.globalAlpha=1;
     }
 
-    // effect panel (fades in with align; carries tau + Delta from scene 2 on)
-    if(align>0.01){
-    ctx.globalAlpha=align;
-    const eTop=H*0.36, eBot=H*0.50, eX=X(0), eMark=X(0)+16;
-    const yOf=(tau)=>eBot-(Math.max(0,Math.min(0.14,tau))/0.14)*(eBot-eTop);
-    const tau0=WSGA.tauMean(WSGA.G0,0,te), tau1=WSGA.tauMean(WSGA.G1,1,te), gap=WSGA.effectGap(te);
-    ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
-    ctx.fillText('EFFECT GAP Δ',eX,eTop-12);
-    ctx.strokeStyle='rgba(29,36,51,0.3)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(eX,eTop);ctx.lineTo(eX,eBot);ctx.stroke();
-    const marker=(tau,color,lab)=>{const y=yOf(tau);ctx.fillStyle=color;ctx.beginPath();ctx.arc(eMark,y,5,0,7);ctx.fill();
-      ctx.font="10px 'IBM Plex Mono',monospace";ctx.textAlign='left';ctx.fillStyle=color;ctx.fillText(lab+' '+(tau*100).toFixed(1)+'pp',eMark+12,y+3);};
-    const y0=yOf(tau0), y1=yOf(tau1), bx=eMark-12;
-    ctx.strokeStyle='rgba(29,36,51,0.4)';ctx.beginPath();ctx.moveTo(eMark,y0);ctx.lineTo(bx,y0);ctx.lineTo(bx,y1);ctx.lineTo(eMark,y1);ctx.stroke();
-    marker(tau0,INK,'τ(G0)');marker(tau1,RED,'τ(G1)');
-    ctx.fillStyle=INK;ctx.font="15px 'IBM Plex Mono',monospace";ctx.textAlign='right';
-    ctx.fillText('Δ '+(gap*100).toFixed(0)+'pp',bx-6,(y0+y1)/2+5);ctx.textAlign='left';
-    ctx.fillStyle=MUTED;ctx.font="10px 'IBM Plex Mono',monospace";
-    const subl = align<0.99 ? 'comparing subgroup effects'
-               : te<0.05 ? 'but is the gap G, or M?'
-               : te<0.95 ? 'holding M constant…'
-               : 'holding M constant';
-    ctx.fillText(subl,eX,eBot+18);
-    ctx.globalAlpha=1;
-    }
+    // effect-gap display: ONE bracket that MORPHS from the scene-1 band gap into the
+    // compact panel (endpoints interpolate by align); panel chrome (axis, tau markers,
+    // value labels, sub-label) fades in; the scene-1 G-band labels fade out.
+    {
+      const tau0=WSGA.tauMean(WSGA.G0,0,te), tau1=WSGA.tauMean(WSGA.G1,1,te), gap=WSGA.effectGap(te);
+      const eTop=H*0.36, eBot=H*0.50, eX=X(0), eMark=X(0)+16;
+      const yOf=(tau)=>eBot-(Math.max(0,Math.min(0.14,tau))/0.14)*(eBot-eTop);
+      // scene-1 anchor: bracket spans the two dot-band centers; scene-2 anchor: panel markers
+      const xB=lerp(W*0.585,eMark,align), yTop=lerp(H*0.42,yOf(tau1),align), yBot=lerp(H*0.60,yOf(tau0),align);
+
+      // panel vertical axis (fades in)
+      if(align>0.01){ctx.globalAlpha=align;ctx.strokeStyle='rgba(29,36,51,0.3)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(eX,eTop);ctx.lineTo(eX,eBot);ctx.stroke();ctx.globalAlpha=1;}
+
+      // the morphing bracket + Delta label (always present)
+      ctx.strokeStyle='rgba(29,36,51,0.45)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(xB+10,yTop);ctx.lineTo(xB,yTop);ctx.lineTo(xB,yBot);ctx.lineTo(xB+10,yBot);ctx.stroke();
+      ctx.fillStyle=INK;ctx.font=Math.round(lerp(16,15,align))+"px 'IBM Plex Mono',monospace";ctx.textAlign='right';
+      ctx.fillText('Δ '+(gap*100).toFixed(0)+'pp',xB-8,(yTop+yBot)/2+5);ctx.textAlign='left';
 
-    // scene-1 explicit effect-gap bracket between the two dot bands (fades out as dots align)
-    if(align<0.99){
-      ctx.globalAlpha=1-align;
-      const yG1=H*0.42, yG0=H*0.60, xBr=W*0.585;
+      // EFFECT GAP header (always), just above the bracket top
       ctx.fillStyle=MUTED;ctx.font="10px 'IBM Plex Mono',monospace";ctx.textAlign='left';
-      ctx.fillText('EFFECT GAP',xBr-2,yG1-H*0.10);
-      ctx.font="11px 'IBM Plex Mono',monospace";
-      ctx.fillStyle=RED;ctx.fillText('G = 1',W*0.925,yG1+4);
-      ctx.fillStyle=INK;ctx.fillText('G = 0',W*0.925,yG0+4);
-      ctx.strokeStyle='rgba(29,36,51,0.45)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(xBr+10,yG1);ctx.lineTo(xBr,yG1);ctx.lineTo(xBr,yG0);ctx.lineTo(xBr+10,yG0);ctx.stroke();
-      ctx.fillStyle=INK;ctx.font="16px 'IBM Plex Mono',monospace";ctx.textAlign='right';
-      ctx.fillText('Δ '+(WSGA.effectGap(te)*100).toFixed(0)+'pp',xBr-8,(yG1+yG0)/2+5);
-      ctx.textAlign='left';ctx.globalAlpha=1;
+      ctx.fillText('EFFECT GAP',xB-2,yTop-lerp(H*0.065,16,align));
+
+      // tau markers + value labels + sub-label (panel chrome) fade in
+      if(align>0.01){
+        ctx.globalAlpha=align;
+        const marker=(tau,color,lab)=>{const y=yOf(tau);ctx.fillStyle=color;ctx.beginPath();ctx.arc(eMark,y,5,0,7);ctx.fill();
+          ctx.font="10px 'IBM Plex Mono',monospace";ctx.textAlign='left';ctx.fillStyle=color;ctx.fillText(lab+' '+(tau*100).toFixed(1)+'pp',eMark+12,y+3);};
+        marker(tau0,INK,'τ(G0)');marker(tau1,RED,'τ(G1)');
+        ctx.fillStyle=MUTED;ctx.font="10px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+        ctx.fillText(te<0.05?'but is the gap G, or M?':te<0.95?'holding M constant…':'holding M constant',eX,eBot+18);
+        ctx.globalAlpha=1;
+      }
+
+      // scene-1 G-band labels fade out
+      if(align<0.99){
+        ctx.globalAlpha=1-align;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
+        ctx.fillStyle=RED;ctx.fillText('G = 1',W*0.925,H*0.42+4);
+        ctx.fillStyle=INK;ctx.fillText('G = 0',W*0.925,H*0.60+4);
+        ctx.globalAlpha=1;
+      }
     }
 
     // scene-05 hidden-dimension cue

From 2fa11c28ff84f3525240d621bfbace592ab1ff93 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 17:12:37 -0400
Subject: [PATCH 09/15] Copy/visual polish: scene-2/3 em-dashes, darker eq
 text, wider dot rows, scene-4 emphasis, Try it!

---
 docs/index.html | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 48cadb7..6794e57 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -31,7 +31,7 @@
   .scene .text{flex:1.15;}
   .scene .panel{flex:1;}
   .scene .mk{font-size:13px;letter-spacing:.3em;text-transform:uppercase;color:var(--red);}
-  .scene .eq{margin:18px 0 22px;border-left:2px solid var(--red);padding:5px 0 5px 15px;color:#3a3f4a;font-size:19px;}
+  .scene .eq{margin:18px 0 22px;border-left:2px solid var(--red);padding:5px 0 5px 15px;color:var(--ink);font-size:19px;}
   .scene h2{font-family:var(--serif);font-weight:400;font-size:clamp(26px,3.6vw,40px);line-height:1.08;letter-spacing:-.015em;margin:0;}
   .scene h2 .ll{color:var(--red);font-style:italic;}
   .scene .supp{color:var(--muted);font-size:14px;line-height:1.6;margin-top:20px;max-width:46ch;}
@@ -84,7 +84,7 @@ <h2>Comparing an effect <span class="ll">across subgroups</span>.</h2>
       <div class="mk">02 · the problem</div>
       <div class="eq" data-tex="\mathbb{E}[M \mid G{=}1] \;\neq\; \mathbb{E}[M \mid G{=}0]"></div>
       <h2><span data-tex="G"></span> is tangled with other moderators <span data-tex="M"></span>.</h2>
-      <div class="supp">Is the effect different by G — or by what G is <em>correlated with</em>? The subgroups don't share the same distribution of M.</div>
+      <div class="supp">Is the effect different by G, or by what G is <em>correlated with</em>? The subgroups don't share the same distribution of M.</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
   </section>
@@ -94,7 +94,7 @@ <h2><span data-tex="G"></span> is tangled with other moderators <span data-tex="
       <div class="mk">03 · the idea</div>
       <div class="eq" data-tex="w_i \;=\; \hat f_{\text{pool}}(M_i) \,/\, \hat f_{G(i)}(M_i)"></div>
       <h2>Up-weight the units that <span class="ll">look like</span> the other group.</h2>
-      <div class="supp">— and down-weight the ones that look like their own. Estimate it from the propensity to belong to G = 1.</div>
+      <div class="supp">Conversely, down-weight the ones that look like their own. Estimate it from the propensity to belong to G = 1.</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
   </section>
@@ -103,7 +103,7 @@ <h2>Up-weight the units that <span class="ll">look like</span> the other group.<
     <div class="text">
       <div class="mk">04 · balance</div>
       <div class="eq" data-tex="\text{std.\,diff}(M) \;\longrightarrow\; 0"></div>
-      <h2>Hold <span data-tex="M"></span> constant, and the true gap <span class="ll">emerges</span>.</h2>
+      <h2>Hold <span data-tex="M"></span> constant, and the <span class="ll">true gap</span> emerges.</h2>
       <div class="supp">With M balanced across subgroups, the effect gap is no longer masked: Δ&prime; = 9 pp, attributable to G.</div>
     </div>
     <div class="panel"><div class="plotframe"></div></div>
@@ -121,7 +121,7 @@ <h2>Observable balance is necessary, not <span class="ll">sufficient</span>.</h2
 </main>
 
 <footer class="site">
-  <h2>Use it.</h2>
+  <h2>Try it!</h2>
   <div class="links">
     <a href="https://github.com/acarril/wsga">GitHub repository</a>
     <a href="simulation-report.html">Monte Carlo simulation report</a>
@@ -216,7 +216,7 @@ <h2>Use it.</h2>
     // dots: 2D cloud (align=0) -> M-axis lane (align=1); radius by weight (te), exaggerated
     const dots=(arr,color,grp)=>{
       for(const p2 of arr){
-        const x=lerp(p2.cxn*W,X(p2.m),align), y=lerp(p2.cyn*H,baseY+10+(grp?9:0),align);
+        const x=lerp(p2.cxn*W,X(p2.m),align), y=lerp(p2.cyn*H,baseY+10+(grp?24:0),align);
         const wv=WSGA.w(p2,te); const r=2.2+Math.pow(Math.max(0.05,wv),0.9)*2.7;
         ctx.globalAlpha=0.5;ctx.beginPath();ctx.arc(x,y,r,0,7);ctx.fillStyle=color;ctx.fill();ctx.globalAlpha=1;
       }
@@ -230,9 +230,9 @@ <h2>Use it.</h2>
       tick(WSGA.G0,INK);tick(WSGA.G1,RED);
       ctx.beginPath();ctx.moveTo(X(0),baseY);ctx.lineTo(X(1),baseY);ctx.strokeStyle='rgba(29,36,51,0.25)';ctx.lineWidth=1;ctx.stroke();
       ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
-      ctx.fillText('STD. DIFF IN M',X(0),baseY+42);
+      ctx.fillText('STD. DIFF IN M',X(0),baseY+58);
       ctx.fillStyle=INK;ctx.font="24px 'IBM Plex Mono',monospace";
-      ctx.fillText(WSGA.stdDiff(te).toFixed(2),X(0),baseY+68);
+      ctx.fillText(WSGA.stdDiff(te).toFixed(2),X(0),baseY+84);
       ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='right';
       ctx.fillText('M →',X(1),baseY+22);ctx.textAlign='left';
       ctx.globalAlpha=1;
@@ -284,10 +284,10 @@ <h2>Use it.</h2>
     if(hidden>0.01){
       ctx.globalAlpha=0.6*hidden;
       ctx.fillStyle=MUTED;ctx.font="11px 'IBM Plex Mono',monospace";ctx.textAlign='left';
-      ctx.fillText('unobserved U — weighting can’t see this',X(0),baseY+94);
-      ctx.strokeStyle='rgba(115,118,126,0.4)';ctx.setLineDash([2,4]);ctx.beginPath();ctx.moveTo(X(0),baseY+110);ctx.lineTo(X(1),baseY+110);ctx.stroke();ctx.setLineDash([]);
+      ctx.fillText('unobserved U — weighting can’t see this',X(0),baseY+114);
+      ctx.strokeStyle='rgba(115,118,126,0.4)';ctx.setLineDash([2,4]);ctx.beginPath();ctx.moveTo(X(0),baseY+130);ctx.lineTo(X(1),baseY+130);ctx.stroke();ctx.setLineDash([]);
       ctx.fillStyle='rgba(115,118,126,0.55)';
-      for(let i=0;i<24;i++){const gx=X(0.05+0.9*((i*0.137)%1));ctx.beginPath();ctx.arc(gx,baseY+110,2.5,0,7);ctx.fill();}
+      for(let i=0;i<24;i++){const gx=X(0.05+0.9*((i*0.137)%1));ctx.beginPath();ctx.arc(gx,baseY+130,2.5,0,7);ctx.fill();}
       ctx.globalAlpha=1;
     }
   };

From 7045d47c599974845e5e566082d87aee61843ac9 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 17:17:23 -0400
Subject: [PATCH 10/15] Darken canvas muted label color for readability (std.
 diff etc.)

---
 docs/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/index.html b/docs/index.html
index 6794e57..9229892 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -167,7 +167,7 @@ <h2>Try it!</h2>
 (function(){
   const cv=document.getElementById('hero'), ctx=cv.getContext('2d');
   const REDUCE = window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches;
-  const INK='#1d2433', RED='#b03a2e', MUTED='#9a958a';
+  const INK='#1d2433', RED='#b03a2e', MUTED='#696b72';
   let W,H,DPR;
   function resize(){DPR=Math.min(2,devicePixelRatio||1);W=cv.clientWidth;H=cv.clientHeight;cv.width=W*DPR;cv.height=H*DPR;ctx.setTransform(DPR,0,0,DPR,0,0);}
 

From a00b6e02bd8b57d279d71baa6f025c9479842841 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 17:24:31 -0400
Subject: [PATCH 11/15] Bold KaTeX text labels (pool, std. diff) so they read
 solid on all displays; revert canvas muted change

---
 docs/index.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 9229892..a4fe29f 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -92,7 +92,7 @@ <h2><span data-tex="G"></span> is tangled with other moderators <span data-tex="
   <section class="scene" data-scene="3">
     <div class="text">
       <div class="mk">03 · the idea</div>
-      <div class="eq" data-tex="w_i \;=\; \hat f_{\text{pool}}(M_i) \,/\, \hat f_{G(i)}(M_i)"></div>
+      <div class="eq" data-tex="w_i \;=\; \hat f_{\textbf{pool}}(M_i) \,/\, \hat f_{G(i)}(M_i)"></div>
       <h2>Up-weight the units that <span class="ll">look like</span> the other group.</h2>
       <div class="supp">Conversely, down-weight the ones that look like their own. Estimate it from the propensity to belong to G = 1.</div>
     </div>
@@ -102,7 +102,7 @@ <h2>Up-weight the units that <span class="ll">look like</span> the other group.<
   <section class="scene" data-scene="4">
     <div class="text">
       <div class="mk">04 · balance</div>
-      <div class="eq" data-tex="\text{std.\,diff}(M) \;\longrightarrow\; 0"></div>
+      <div class="eq" data-tex="\textbf{std.\,diff}(M) \;\longrightarrow\; 0"></div>
       <h2>Hold <span data-tex="M"></span> constant, and the <span class="ll">true gap</span> emerges.</h2>
       <div class="supp">With M balanced across subgroups, the effect gap is no longer masked: Δ&prime; = 9 pp, attributable to G.</div>
     </div>
@@ -167,7 +167,7 @@ <h2>Try it!</h2>
 (function(){
   const cv=document.getElementById('hero'), ctx=cv.getContext('2d');
   const REDUCE = window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches;
-  const INK='#1d2433', RED='#b03a2e', MUTED='#696b72';
+  const INK='#1d2433', RED='#b03a2e', MUTED='#9a958a';
   let W,H,DPR;
   function resize(){DPR=Math.min(2,devicePixelRatio||1);W=cv.clientWidth;H=cv.clientHeight;cv.width=W*DPR;cv.height=H*DPR;ctx.setTransform(DPR,0,0,DPR,0,0);}
 

From 0fbd8ab07b77b8a57a4792e2004936cd3a304934 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 17:28:44 -0400
Subject: [PATCH 12/15] Fix faint KaTeX text: override
 -webkit-font-smoothing:auto on equations (macOS antialiased was lightening
 roman font)

---
 docs/index.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index a4fe29f..1c4e46a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -31,7 +31,7 @@
   .scene .text{flex:1.15;}
   .scene .panel{flex:1;}
   .scene .mk{font-size:13px;letter-spacing:.3em;text-transform:uppercase;color:var(--red);}
-  .scene .eq{margin:18px 0 22px;border-left:2px solid var(--red);padding:5px 0 5px 15px;color:var(--ink);font-size:19px;}
+  .scene .eq{margin:18px 0 22px;border-left:2px solid var(--red);padding:5px 0 5px 15px;color:var(--ink);font-size:19px;-webkit-font-smoothing:auto;}
   .scene h2{font-family:var(--serif);font-weight:400;font-size:clamp(26px,3.6vw,40px);line-height:1.08;letter-spacing:-.015em;margin:0;}
   .scene h2 .ll{color:var(--red);font-style:italic;}
   .scene .supp{color:var(--muted);font-size:14px;line-height:1.6;margin-top:20px;max-width:46ch;}
@@ -92,7 +92,7 @@ <h2><span data-tex="G"></span> is tangled with other moderators <span data-tex="
   <section class="scene" data-scene="3">
     <div class="text">
       <div class="mk">03 · the idea</div>
-      <div class="eq" data-tex="w_i \;=\; \hat f_{\textbf{pool}}(M_i) \,/\, \hat f_{G(i)}(M_i)"></div>
+      <div class="eq" data-tex="w_i \;=\; \hat f_{\text{pool}}(M_i) \,/\, \hat f_{G(i)}(M_i)"></div>
       <h2>Up-weight the units that <span class="ll">look like</span> the other group.</h2>
       <div class="supp">Conversely, down-weight the ones that look like their own. Estimate it from the propensity to belong to G = 1.</div>
     </div>
@@ -102,7 +102,7 @@ <h2>Up-weight the units that <span class="ll">look like</span> the other group.<
   <section class="scene" data-scene="4">
     <div class="text">
       <div class="mk">04 · balance</div>
-      <div class="eq" data-tex="\textbf{std.\,diff}(M) \;\longrightarrow\; 0"></div>
+      <div class="eq" data-tex="\text{std.\,diff}(M) \;\longrightarrow\; 0"></div>
       <h2>Hold <span data-tex="M"></span> constant, and the <span class="ll">true gap</span> emerges.</h2>
       <div class="supp">With M balanced across subgroups, the effect gap is no longer masked: Δ&prime; = 9 pp, attributable to G.</div>
     </div>

From 1d277d2972b347de92e1920e2f62afc1505eb9c4 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 17:33:08 -0400
Subject: [PATCH 13/15] Remove redundant effect-panel axis bar; revert eq
 font-smoothing override

---
 docs/index.html | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 1c4e46a..fba5deb 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -31,7 +31,7 @@
   .scene .text{flex:1.15;}
   .scene .panel{flex:1;}
   .scene .mk{font-size:13px;letter-spacing:.3em;text-transform:uppercase;color:var(--red);}
-  .scene .eq{margin:18px 0 22px;border-left:2px solid var(--red);padding:5px 0 5px 15px;color:var(--ink);font-size:19px;-webkit-font-smoothing:auto;}
+  .scene .eq{margin:18px 0 22px;border-left:2px solid var(--red);padding:5px 0 5px 15px;color:var(--ink);font-size:19px;}
   .scene h2{font-family:var(--serif);font-weight:400;font-size:clamp(26px,3.6vw,40px);line-height:1.08;letter-spacing:-.015em;margin:0;}
   .scene h2 .ll{color:var(--red);font-style:italic;}
   .scene .supp{color:var(--muted);font-size:14px;line-height:1.6;margin-top:20px;max-width:46ch;}
@@ -248,9 +248,6 @@ <h2>Try it!</h2>
       // scene-1 anchor: bracket spans the two dot-band centers; scene-2 anchor: panel markers
       const xB=lerp(W*0.585,eMark,align), yTop=lerp(H*0.42,yOf(tau1),align), yBot=lerp(H*0.60,yOf(tau0),align);
 
-      // panel vertical axis (fades in)
-      if(align>0.01){ctx.globalAlpha=align;ctx.strokeStyle='rgba(29,36,51,0.3)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(eX,eTop);ctx.lineTo(eX,eBot);ctx.stroke();ctx.globalAlpha=1;}
-
       // the morphing bracket + Delta label (always present)
       ctx.strokeStyle='rgba(29,36,51,0.45)';ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(xB+10,yTop);ctx.lineTo(xB,yTop);ctx.lineTo(xB,yBot);ctx.lineTo(xB+10,yBot);ctx.stroke();
       ctx.fillStyle=INK;ctx.font=Math.round(lerp(16,15,align))+"px 'IBM Plex Mono',monospace";ctx.textAlign='right';

From 2bed196e46ed163cf30d9d4da2ee337d438e9d64 Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Fri, 29 May 2026 17:38:19 -0400
Subject: [PATCH 14/15] Release pinned figure at end: translate canvas up as
 footer enters so it rides above, not buried

---
 docs/index.html | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index fba5deb..4f3c8c8 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -301,12 +301,21 @@ <h2>Try it!</h2>
       hidden:seg(top(4)-vh*0.6, top(4))          // scene 5 cue
     };
   }
+  // release the pinned canvas at the end: once the footer enters the viewport, translate
+  // the figure up by the same amount so it rides just above the footer and scrolls away
+  // cleanly (instead of the footer covering it).
+  const footerEl=document.querySelector('footer.site');
+  function parkCanvas(){
+    const y=window.scrollY||window.pageYOffset||0;
+    const over=Math.max(0, y+window.innerHeight-footerEl.offsetTop);
+    cv.style.transform = over>0 ? 'translateY('+(-over)+'px)' : '';
+  }
   let ticking=false;
-  function frame(){window.__p=progress();drawHero(window.__p);ticking=false;}
+  function frame(){window.__p=progress();drawHero(window.__p);parkCanvas();ticking=false;}
   function onScroll(){if(ticking)return;ticking=true;requestAnimationFrame(frame);}
-  addEventListener('resize',()=>{resize();drawHero(window.__p||{align:0,t:0,hidden:0});});
-  if(REDUCE){ resize();window.__p={align:1,t:1,hidden:0};drawHero(window.__p); }
-  else { addEventListener('scroll',onScroll,{passive:true});resize();window.__p=progress();drawHero(window.__p); }
+  addEventListener('resize',()=>{resize();drawHero(window.__p||{align:0,t:0,hidden:0});parkCanvas();});
+  if(REDUCE){ resize();window.__p={align:1,t:1,hidden:0};drawHero(window.__p);parkCanvas();addEventListener('scroll',()=>requestAnimationFrame(parkCanvas),{passive:true}); }
+  else { addEventListener('scroll',onScroll,{passive:true});resize();window.__p=progress();drawHero(window.__p);parkCanvas(); }
 })();
 </script>
 <script>

From a8089e6f798e04aa27fe7646cfd302c2785021fa Mon Sep 17 00:00:00 2001
From: Alvaro Carril <alvarocarril@gmail.com>
Date: Sat, 30 May 2026 07:13:42 -0400
Subject: [PATCH 15/15] Dock figure flush near top during scene 5 (rise on
 scene 4->5); revert ride-and-exit

---
 docs/index.html | 25 ++++++++++---------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 4f3c8c8..1bafaf3 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -191,8 +191,10 @@ <h2>Try it!</h2>
   function lerp(a,b,u){return a+(b-a)*u;}
 
   window.drawHero=function(p){
-    p=p||{}; const align=clamp(p.align||0), te=ease(clamp(p.t||0)), hidden=clamp(p.hidden||0);
+    p=p||{}; const align=clamp(p.align||0), te=ease(clamp(p.t||0)), hidden=clamp(p.hidden||0), dock=ease(clamp(p.dock||0));
     ctx.clearRect(0,0,W,H);
+    ctx.save();
+    ctx.translate(0, -dock*H*0.30);   // dock the figure flush near the top during scene 5
     const baseY=(W<=760?H*0.78:H*0.70), amp=H*0.18;
 
     // curves (fade in with align; reweight with te)
@@ -287,6 +289,7 @@ <h2>Try it!</h2>
       for(let i=0;i<24;i++){const gx=X(0.05+0.9*((i*0.137)%1));ctx.beginPath();ctx.arc(gx,baseY+130,2.5,0,7);ctx.fill();}
       ctx.globalAlpha=1;
     }
+    ctx.restore();
   };
 
   // ---- phased scroll timeline ----
@@ -298,24 +301,16 @@ <h2>Try it!</h2>
     return {
       align: seg(top(0),top(1)),                 // phase A: scene 1 -> 2
       t:     seg(top(1),top(3)),                 // phase B: scene 2 -> 4 (=1 from scene 4 on)
-      hidden:seg(top(4)-vh*0.6, top(4))          // scene 5 cue
+      hidden:seg(top(4)-vh*0.6, top(4)),         // scene 5 cue
+      dock:  seg(top(3),top(4))                  // scene 4 -> 5: figure rises to dock at top
     };
   }
-  // release the pinned canvas at the end: once the footer enters the viewport, translate
-  // the figure up by the same amount so it rides just above the footer and scrolls away
-  // cleanly (instead of the footer covering it).
-  const footerEl=document.querySelector('footer.site');
-  function parkCanvas(){
-    const y=window.scrollY||window.pageYOffset||0;
-    const over=Math.max(0, y+window.innerHeight-footerEl.offsetTop);
-    cv.style.transform = over>0 ? 'translateY('+(-over)+'px)' : '';
-  }
   let ticking=false;
-  function frame(){window.__p=progress();drawHero(window.__p);parkCanvas();ticking=false;}
+  function frame(){window.__p=progress();drawHero(window.__p);ticking=false;}
   function onScroll(){if(ticking)return;ticking=true;requestAnimationFrame(frame);}
-  addEventListener('resize',()=>{resize();drawHero(window.__p||{align:0,t:0,hidden:0});parkCanvas();});
-  if(REDUCE){ resize();window.__p={align:1,t:1,hidden:0};drawHero(window.__p);parkCanvas();addEventListener('scroll',()=>requestAnimationFrame(parkCanvas),{passive:true}); }
-  else { addEventListener('scroll',onScroll,{passive:true});resize();window.__p=progress();drawHero(window.__p);parkCanvas(); }
+  addEventListener('resize',()=>{resize();drawHero(window.__p||{align:0,t:0,hidden:0});});
+  if(REDUCE){ resize();window.__p={align:1,t:1,hidden:0};drawHero(window.__p); }
+  else { addEventListener('scroll',onScroll,{passive:true});resize();window.__p=progress();drawHero(window.__p); }
 })();
 </script>
 <script>