# 音流·溯城 · River

**sound flow · city upstream** — 一条由声音构筑的流动场域。留下你的呼吸，看它如何随时间被河水慢慢遗忘。

A browser-based ambient sound installation set on Shanghai's Suzhou Creek → Huangpu River. Visitors leave a voice; it drifts downstream, is weathered by entropic decay, and is finally erased at the estuary. This repository is the complete, self-contained front-end — a landing site that flows directly into the five-stage installation experience.

---

## 体验流程 · The experience

```
index.html  (落地页 landing)
   │   滚动叙事：三种声音 · 机理 · 五段河流 · 场域预览
   │   final CTA「触碰，进入场域」
   ▼
installation/index.html  (装置流程 installation flow)
   隐私 privacy → 入场 entry → 唤醒 awakening → 投递 contribution → 沉浸 immersion
```

- **Landing** (`index.html`) — single-page scroll: hero with a live WebGL water shader painted onto the real Shanghai map, the three sound ecologies, the decay mechanism, the five river zones, and a framed preview of the field.
- **Installation** (`installation/index.html`) — the React click-through. The final *immersion* stage is the **live MapLibre map** of Shanghai (Suzhou Creek → Huangpu → estuary) with Chinese place labels, cyan water glow, drifting/stationed sound nodes, and your amber self node. Tap any glowing node — or the bottom 「你的声 · 在场」dock — to open the **「你的声」playback window** (who, time-since, length, entropy, an entropy-eroded waveform, and a single *listen* control). Drag to pan · scroll/pinch to zoom · two-finger drag to tilt.

Both are **static** — no build step. Open `index.html` in a browser, or serve the folder.

---

## 本地运行 · Run locally

```bash
# 任意静态服务器即可 — any static server works
npx serve .
# 或 / or
python3 -m http.server 8000
```

Then open `http://localhost:3000` (serve) or `http://localhost:8000`.

> 直接双击 `index.html` 也能跑，但用本地服务器更可靠（避免个别浏览器对 `file://` 的限制）。
> Opening `index.html` directly works too, but a local server is more reliable.

### 联网依赖 · Network dependencies
This is a zero-build site that pulls a few libraries from CDNs at runtime:
- **Google Fonts** — Noto Sans SC / Noto Serif SC / JetBrains Mono / Cormorant Garamond
- **three.js** (landing hero water shader)
- **React 18 + Babel standalone** (installation flow — JSX is transpiled in the browser)
- **MapLibre GL JS + CARTO dark-matter tiles** (immersion stage — the live Shanghai map)

An internet connection is required (the immersion map streams vector tiles). No API keys, no backend.

---

## 目录结构 · Structure

```
.
├── index.html                  landing page — entry point
├── landing.css                 landing styles
├── landing.js                  landing scroll/reveal behaviour
├── landing-hero-water.js       WebGL water shader over the hero map
├── colors_and_type.css         shared design tokens (color · type · motion)
├── assets/                     wordmarks, monogram, maps, <liquid-wordmark>
└── installation/               the 5-stage React installation
    ├── index.html              app shell + stage orchestration
    ├── MapBackdrop.jsx         live MapLibre river map + tappable sound nodes
    ├── rivergeo.js             river-progress → real lng/lat projection
    ├── PrivacyNotice.jsx       隐私
    ├── EntryGate.jsx           入场 (liquid-chrome wordmark)
    ├── AwakeningRing.jsx       唤醒
    ├── RecordingUI.jsx         投递 (press-and-hold to record)
    ├── VoicePlayback.jsx       「你的声」playback window
    └── DebugConsole.jsx        runtime tuning console (dev only)
```

A flow strip at the top of the installation lets you jump between stages; the bottom-right toggle opens the debug console. Both are kit/dev affordances and would not ship in the gallery build.

---

## 设计系统 · Design language

All color, type, spacing, radius and motion tokens live in `colors_and_type.css`. The system is deliberately dark and low-contrast: near-black surfaces, a single shimmering teal-cyan accent, a rare sediment-amber for human-presence signals, wide letter-spacing, light weights only, and slow `cubic-bezier(0.16, 1, 0.3, 1)` motion. No bold, no bright fills, no rounded-card UI.

---

## License

© 2026 · jack yunhao jia · **AGPL-3.0** — see [`LICENSE`](./LICENSE).