|
1 | 1 | # Design Rationale — Emergence in a Cup |
2 | 2 |
|
3 | | -> Written deliverable for the assignment. A companion ~5-minute video script lives |
4 | | -> at the bottom. Status: built and deployed at |
5 | | -> <https://emergence-in-a-cup.vercel.app/>; video recording pending. |
| 3 | +> This is the written deliverable for the assignment. A companion ~5-minute video |
| 4 | +> script is at the bottom. Status: built and live at |
| 5 | +> <https://emergence-in-a-cup.vercel.app/>. The video recording is still pending. |
6 | 6 |
|
7 | | -## Why this theme & approach (Theme 1: Exploration & Understanding) |
| 7 | +## Why this theme and approach (Theme 1: Exploration & Understanding) |
8 | 8 |
|
9 | | -Emergent dynamics — simple local rules producing complex global patterns — is one |
10 | | -of the most important ideas in science and one of the hardest to feel from text. |
11 | | -People bounce off it because it's taught abstractly. The bet here: teach it |
12 | | -through something millions of people already love and have physically held — **latte |
13 | | -art** — and end on a **real fluid simulator** the learner drives themselves. The |
14 | | -familiar object carries the abstract idea. |
| 9 | +The heart in a latte is a real example of one of science's biggest ideas: |
| 10 | +**emergence** — how simple rules, repeated over and over, add up to complex |
| 11 | +patterns. It's a powerful idea, but a hard one to _feel_, because it's almost |
| 12 | +always taught with abstract words. |
15 | 13 |
|
16 | | -## What makes it non-obvious |
| 14 | +So I started from something millions of people have already held in their hands: |
| 15 | +**latte art**. The familiar object carries the abstract idea. The page walks you |
| 16 | +from the small-scale "rules" (foam, density, heat) up to the big-picture patterns, |
| 17 | +and then hands you a **real, playable fluid simulator** so you can pour your own |
| 18 | +cup and watch the patterns appear. You learn it by doing it. |
| 19 | + |
| 20 | +## What makes it interesting and non-obvious |
17 | 21 |
|
18 | 22 | - **Latte art is genuinely emergent, and there's real peer-reviewed science behind |
19 | | - it** (Princeton/Stone lab, _Nature Communications_ 2017; _J. Fluid Mech._ 2020 on |
20 | | - double-diffusive convection). The connection isn't a cute metaphor — pour |
21 | | - velocity is a literal control parameter for whether a cup mixes or layers. |
22 | | -- **Two-track fidelity strategy.** The Section 5 simulator is a real GPU |
23 | | - Navier–Stokes fluid solver (max fidelity, the "wow"). The teaching demos in |
24 | | - Sections 3–4 deliberately use the _simplest_ technique that makes each idea |
25 | | - obvious (Canvas2D particles for self-organization; a chaotic double-gyre flow for |
26 | | - sensitivity to initial conditions). Clarity beats realism where the goal is |
27 | | - comprehension. |
28 | | - |
29 | | -## Key design decisions & tradeoffs |
30 | | - |
31 | | -| Decision | Why | Tradeoff | |
32 | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | |
33 | | -| **Direct raw-WebGL port** of the PourMyFriends sim (actual `.vert`/`.frag` files, dual-res sim/dye, MacCormack, milk+crema dye, cup mask, latte-art display) | Faithfulness to the real fidelity target beats an in-spirit rewrite; the imperative multi-pass pipeline (feedback-loop handling, scratch buffers) ports cleanly as-is | More code than a wrapper; WebGL2 preferred with WebGL1 half-float fallback | |
34 | | -| **Framer Motion** for scroll reveals | Declarative `whileInView`, first-class reduced-motion | A client dependency; gated behind `useReducedMotion` | |
35 | | -| **Typed content modules + citations.ts** | Every claim traces to a verified source at compile time | More plumbing than inline copy — worth it for trust | |
36 | | -| **Graceful static fallback** | The page must read beautifully with no WebGL / reduced motion | A second rendering path to maintain | |
37 | | -| **Research validation as a graded first step** | Caught a corrupted Princeton URL and a mis-attributed viscoelasticity claim in the seed | Time spent before any feature code | |
38 | | - |
39 | | -## What I'd change / extend next |
40 | | - |
41 | | -- Mixed-resolution fluid (high-res dye, low-res velocity) + a dye/foam channel for |
42 | | - sharper rosetta edges and crema sheen closer to PourMyFriends. |
43 | | -- A "layered latte" mode in the simulator that demonstrates the critical pour |
44 | | - velocity directly (mix vs. stratify), tying Section 4 science to Section 5 play. |
45 | | -- Save/share a pour; a guided "make a heart" tutorial overlay. |
46 | | -- Finish History/Recap polish and add a pour-sound layer. |
47 | | - |
48 | | -## AI-development transparency |
49 | | - |
50 | | -This was built with Claude Code under active human direction: I set the theme and |
51 | | -quality bar, approved the architecture and library choices, validated the science, |
52 | | -and reviewed the live build in-browser (the simulator's WebGL setup was debugged |
53 | | -from a real console error → fix). Claude Code transcripts are captured and submitted |
54 | | -alongside this repo; the judgment calls are visible throughout, not a blind |
55 | | -generate. |
| 23 | + it.** This isn't a cute metaphor. Researchers at Princeton (Stone lab) published |
| 24 | + on it in _Nature Communications_ (2017) and _Journal of Fluid Mechanics_ (2020). |
| 25 | + The key finding: how fast you pour is what decides whether the cup blends into one |
| 26 | + color or settles into clean layers. The same physical idea — two liquids of |
| 27 | + different temperature and density meeting and stacking up — is called |
| 28 | + double-diffusive convection. |
| 29 | +- **Two different levels of fidelity, on purpose.** The big simulator at the end is |
| 30 | + the real thing: a true physics simulation of moving liquid, the same kind of math |
| 31 | + used for smoke and water in films and games. That's the "wow." But the small |
| 32 | + teaching demos earlier in the page deliberately use the _simplest_ method that |
| 33 | + makes each idea click — for example, simple moving dots to show how order appears |
| 34 | + on its own, and a swirling test flow to show how two nearly identical pours drift |
| 35 | + apart. When the goal is understanding, clarity beats realism. |
| 36 | + |
| 37 | +## Key design decisions and tradeoffs |
| 38 | + |
| 39 | +| Decision | Why | Tradeoff | |
| 40 | +| ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- | |
| 41 | +| **Faithfully port a real fluid simulator (PourMyFriends)** rather than write a simplified one | A real simulation is far more convincing than something that only looks the part | More code than a shortcut, but it behaves like real fluid | |
| 42 | +| **Run the physics coarse and the coloring fine** | Keeps it fast _and_ detailed, and it works on older graphics hardware too | Two moving parts to keep in sync | |
| 43 | +| **Framer Motion for scroll animations** | Animations play as you scroll a section into view, and turn off for people who prefer less motion | One extra library to depend on | |
| 44 | +| **Keep all the writing in typed content files with a citations list** | Every claim is tied to a checked source, automatically | More setup than just typing text into the page | |
| 45 | +| **A clean static fallback** | The page still reads beautifully when animations or the simulator can't run | A second version of the visuals to maintain | |
| 46 | +| **Check the science first, before any code** | This caught a broken Princeton link and a wrongly-attributed claim in the source notes | Time spent up front, before anything was visible | |
| 47 | + |
| 48 | +## What I'd change or add next |
| 49 | + |
| 50 | +- Sharper, prettier pour patterns — more detail in the color and a glossier crema |
| 51 | + (the brown foam on top) to get closer to the original simulator. |
| 52 | +- A "layered latte" mode in the simulator that lets you find the exact pour speed |
| 53 | + where the cup flips from blending to forming layers — connecting the science |
| 54 | + earlier on the page directly to the thing you're playing with. |
| 55 | +- Let people save and share a pour, plus a guided "make a heart" tutorial. |
| 56 | +- Finish polishing the History and Recap sections, and add a pouring sound. |
| 57 | + |
| 58 | +## How AI was used in development |
| 59 | + |
| 60 | +I built this with Claude Code, under active human direction. I set the topic and |
| 61 | +the quality bar, approved the architecture and the tools, checked the science |
| 62 | +myself, and reviewed the live site in the browser — for example, the simulator's |
| 63 | +graphics setup was debugged from a real error in the browser console and then |
| 64 | +fixed. The Claude Code transcripts are included with this repo, so the judgment |
| 65 | +calls are visible throughout. This wasn't a blind "generate and ship." |
56 | 66 |
|
57 | 67 | ## Approximate time spent |
58 | 68 |
|
59 | | -- Research validation + plan: ~0.75h |
60 | | -- Scaffold + tooling + Claude Code fleet: ~1h |
61 | | -- First vertical slice (hero, micro, macro, simulator, nav, demos): ~2h |
62 | | -- In-browser verification + fixes: ~0.5h |
| 69 | +- Checking the science + planning: ~0.75h |
| 70 | +- Project setup, tooling, and Claude Code agents: ~1h |
| 71 | +- First working version (hero, micro, macro, simulator, navigation, demos): ~2h |
| 72 | +- Testing in the browser + fixes: ~0.5h |
63 | 73 |
|
64 | 74 | --- |
65 | 75 |
|
66 | 76 | ## ~5-minute video script (outline) |
67 | 77 |
|
68 | | -1. **(0:00–0:30) Hook.** Show the hero. "The heart in your latte is emergence — and |
69 | | - nobody draws it." State the promise: leave able to explain emergence, through |
70 | | - coffee. |
71 | | -2. **(0:30–1:15) Why this is hard / why coffee.** Emergence is abstract; latte art |
72 | | - is a thing you've held. Two-track plan: teach simply, pay off with a real sim. |
73 | | -3. **(1:15–2:15) Micro → Macro.** Scroll the buoyancy demo (same rule per particle → |
74 | | - a foam layer). Then the sensitivity demo (two near-identical pours diverge). |
75 | | - Name the concepts as the cards appear. |
76 | | -4. **(2:15–2:45) The science is real.** Princeton double-diffusive convection; |
77 | | - show the corrected citation and the layered-latte illustration. Note the |
78 | | - research-validation step caught a broken source. |
79 | | -5. **(2:45–3:45) The payoff.** Drive the WebGL simulator live — pour, change height/ |
80 | | - speed/temp, watch patterns emerge; show the graceful fallback. |
81 | | -6. **(3:45–4:30) Architecture & decisions.** raw-WebGL/Framer Motion, typed-content + |
82 | | - citations, accessibility (reduced-motion, keyboard), the agent fleet. |
83 | | -7. **(4:30–5:00) Extensions + AI transparency.** What I'd build next; how human |
84 | | - direction shaped the build; transcripts included. |
| 78 | +1. **(0:00–0:30) Hook.** Show the hero. "The heart in your latte is emergence — |
| 79 | + and almost nobody realizes it." State the promise: you'll leave able to explain |
| 80 | + emergence, through coffee. |
| 81 | +2. **(0:30–1:15) Why this is hard, and why coffee.** Emergence is abstract; latte |
| 82 | + art is something you've physically held. Lay out the plan: teach it simply, then |
| 83 | + pay it off with a real simulator. |
| 84 | +3. **(1:15–2:15) Small scale to big scale.** Scroll through the foam demo (the same |
| 85 | + rule on each particle adds up to a foam layer). Then the sensitivity demo (two |
| 86 | + nearly identical pours end up looking different). Name each concept as its card |
| 87 | + appears. |
| 88 | +4. **(2:15–2:45) The science is real.** Show the Princeton work on layering, the |
| 89 | + corrected citation, and the layered-latte illustration. Mention that checking |
| 90 | + the science up front caught a broken source. |
| 91 | +5. **(2:45–3:45) The payoff.** Pour in the real simulator live — change the height, |
| 92 | + speed, and milk temperature, and watch patterns form. Show the clean fallback |
| 93 | + version too. |
| 94 | +6. **(3:45–4:30) Architecture and decisions.** The ported fluid simulator, the |
| 95 | + animation choices, keeping all claims tied to sources, and accessibility |
| 96 | + (reduced motion, keyboard support), plus the team of Claude Code agents. |
| 97 | +7. **(4:30–5:00) What's next + AI transparency.** What I'd build with more time, |
| 98 | + how human direction shaped the build, and the included transcripts. |
0 commit comments