v0.1.0 initial commit

2026-07-15 01:28:56 -04:00
commit 874abee663
35 changed files with 3486 additions and 0 deletions
@@ -0,0 +1,6 @@
+bin/
+log/
+dev/
+debug/
+catalog.txt
+build.sh
@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Lixen Wraith
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,23 @@
+GO := go
+
+.PHONY: build build-term build-raylib test clean android-aar
+
+build: build-term
+
+build-term:
+	$(GO) build -o bin/symph-term ./cmd/symph-term
+
+# purego backend: no cgo, embedded raylib .so for linux amd64/arm64
+build-raylib:
+	CGO_ENABLED=0 $(GO) build -o bin/symph-raylib ./cmd/symph-raylib
+
+test:
+	$(GO) test ./...
+
+# TODO: blocked on mobile/ facade (Dispatch/Update/snapshot exports)
+android-aar:
+	gomobile bind -target=android -o build/symph.aar ./mobile
+
+clean:
+	rm -rf bin build
+
@@ -0,0 +1,88 @@
+# Symph
+
+Rhythm-driven grid traversal. Real-time spatial movement over a quantized musical beat, on a 3×3 grid.
+
+## Concept
+
+A song advances one chord at a time on the beat (the Z-axis). Each chord is a 3×3 matrix of notes. The player holds a cell on the grid and moves across lanes (X) and rows (Y) to collect items and avoid walls. Lane shifts persist; row shifts are transient and collapse back to the base row after a fixed number of chords — a jump you must ride out or duck out of. Returning into a wall on landing is fatal.
+
+The engine is a deterministic, side-effect-free state machine. Rendering and input polling run at host framerate (~60Hz), decoupled from beat progression. Frontends translate native input to platform-neutral actions and drain queued gameplay events into audio.
+
+## Mechanics
+
+| Item | Glyph | Effect |
+|---|---|---|
+| Energy | `*` | +1 energy, consumed on contact |
+| Magnet | `M` | sweeps every Energy note in the lookahead window, all grid positions |
+| Shield | `S` | arms one absorb charge; no expiry |
+| Boost  | `B` | doubles tempo for a fixed duration; refreshes, does not stack |
+| Wall   | `#` | fatal, unless a charge absorbs it or a Boost is active |
+
+Two persistent effects (Shield charges, Boost deadline) cross level boundaries and clear on death. A Boost grants wall immunity but the field keeps rendering walls lethal — Boost expiry inside a wall band is the primary death mode.
+
+## Build
+
+```sh
+make build-term      # terminal frontend (symph-term)
+make build-raylib    # raylib frontend, linux only (symph-raylib)
+make test
+```
+
+Requires Go 1.26+. The raylib frontend builds CGO-free (embedded `.so`, linux amd64/arm64).
+
+## Run
+
+```sh
+bin/symph-term
+```
+
+### Controls
+
+Vim-style bindings:
+
+- `h` `j` `k` `l` — left, down, up, right
+- `Enter` — restart after game over
+- `Ctrl+S` — toggle mute
+- `Esc` / `Ctrl+C` / `q` — quit
+
+Host controls (quit, mute) bypass the engine and work in every phase, including paused.
+
+## Frontends
+
+- **Terminal** (`symph-term`): full Unicode glyph set, density-shaded walls, wall-band colored borders. Pauses and shows a notice below minimum viewport size.
+- **Raylib** (`symph-raylib`, linux): same presentation contract, drawn with primitives. Substitutes ASCII for the Unicode atlas (default font covers codepoints 32..126); draws walls as rectangles.
+
+Both share the grid-scan and burn-out projection pipeline in `render`; presentation policy lives there, not in the engine.
+
+## Audio
+
+Fire-and-forget effects, PCM synthesized at startup. PipeWire backend (`pw-play`) on Linux; silent `nullEngine` elsewhere or when `pw-play` is absent — the game stays playable without audio. FreeBSD (sndio/OSS) is unimplemented and falls through to silence.
+
+## Layout
+
+Unidirectional dependency flow (supports a future CGO/gomobile mobile target):
+
+- `types/` — dependency-free structures and the value registry (identity, glyph, polarity)
+- `parameter/` — compile-time constants: grid bounds, timings, glyphs, geometry
+- `game/` — pure state engine; contact behavior and persistent effects
+- `input/` — native key → neutral `Key` → `game.Action`
+- `render/` — appearance tables and the shared draw pipeline; `render/raylib/` is the graphical frontend
+- `audio/` — synthesized effects and platform backends
+- `cmd/` — hosts: wiring, event poller, ticker
+
+Adding an item kind is three rows — identity (`types.valueSpecs`), behavior (`game.resolvers`), appearance (`render.valueVisuals`) — with no switch edits. `init` asserts registry completeness at process start.
+
+## Status
+
+Early development. Terminal and raylib frontends are functional.
+
+Planned:
+- **Android** frontend via `gomobile` (`mobile/`, `platform/android/`). The `input` package is bypassed on that path — touch/gesture translates directly to `game.Action`.
+- Symphony (multi-song) and Symphace (bounded environment) domain layers.
+- Persistent audio stream to replace per-effect `pw-play` spawns before latency matters.
+- FreeBSD audio backend (sndio/OSS).
+
+## License
+
+See `LICENSE`.
+
@@ -0,0 +1,35 @@
+// Package audio provides fire-and-forget sound effect playback.
+// Placeholder backend: pre-synthesized WAVs spawned via pw-play (PipeWire).
+// Per-spawn stream connect costs ~tens of ms; replace with a persistent
+// stream (libpipewire CGO or raylib audio) once latency matters
+package audio
+
+// Effect identifies a synthesized sound effect
+type Effect uint8
+
+const (
+	EffectNone Effect = iota
+	EffectPickup
+	EffectMagnet
+	EffectShield
+	EffectShieldBreak
+	EffectBoost
+	EffectDeflect
+	EffectMoveRow
+	EffectMoveLane
+	EffectHitWall
+	EffectLevelClear
+	EffectCount
+)
+
+// Engine plays effects without blocking the caller
+type Engine interface {
+	Play(Effect) // EffectNone is a no-op
+	Close()
+}
+
+// nullEngine is the silent fallback (unsupported platform, pw-play absent)
+type nullEngine struct{}
+
+func (nullEngine) Play(Effect) {}
+func (nullEngine) Close()      {}
@@ -0,0 +1,7 @@
+//go:build !linux
+
+package audio
+
+// NewEngine returns the silent engine on platforms without a backend
+// (FreeBSD path pending: sndio/OSS)
+func NewEngine() Engine { return nullEngine{} }
@@ -0,0 +1,30 @@
+package audio
+
+import "symph/game"
+
+// MapGameEvent translates engine gameplay events to sound effects
+func MapGameEvent(e game.Event) Effect {
+	switch e {
+	case game.EventPickup:
+		return EffectPickup
+	case game.EventMagnet:
+		return EffectMagnet
+	case game.EventShield:
+		return EffectShield
+	case game.EventShieldBreak:
+		return EffectShieldBreak
+	case game.EventBoost:
+		return EffectBoost
+	case game.EventDeflect:
+		return EffectDeflect
+	case game.EventMoveRow:
+		return EffectMoveRow
+	case game.EventMoveLane:
+		return EffectMoveLane
+	case game.EventHitWall:
+		return EffectHitWall
+	case game.EventLevelClear:
+		return EffectLevelClear
+	}
+	return EffectNone
+}
@@ -0,0 +1,27 @@
+package audio
+
+// Muter gates playback of a wrapped Engine. The mute state is a host concern:
+// the engine state machine is unaware and both backends stay untouched
+type Muter struct {
+	Engine
+	muted bool
+}
+
+func NewMuter(e Engine) *Muter { return &Muter{Engine: e} }
+
+// Play forwards to the wrapped Engine unless gated. In-flight pw-play
+// processes are not killed; effects are under 300ms
+func (m *Muter) Play(fx Effect) {
+	if !m.muted {
+		m.Engine.Play(fx)
+	}
+}
+
+// Toggle flips the gate and reports the new muted state
+func (m *Muter) Toggle() bool {
+	m.muted = !m.muted
+	return m.muted
+}
+
+// Muted reports whether playback is gated
+func (m *Muter) Muted() bool { return m.muted }
@@ -0,0 +1,53 @@
+//go:build linux
+
+package audio
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+)
+
+// pwEngine plays pre-rendered WAVs by spawning pw-play per effect
+type pwEngine struct {
+	dir   string
+	files [EffectCount]string
+}
+
+// NewEngine synthesizes effect WAVs into a temp dir. Falls back to a silent
+// engine when pw-play is unavailable — game remains playable without audio
+func NewEngine() Engine {
+	if _, err := exec.LookPath("pw-play"); err != nil {
+		return nullEngine{}
+	}
+	dir, err := os.MkdirTemp("", "symph-sfx-")
+	if err != nil {
+		return nullEngine{}
+	}
+	e := &pwEngine{dir: dir}
+	for fx := EffectNone + 1; fx < EffectCount; fx++ {
+		path := filepath.Join(dir, fmt.Sprintf("fx-%d.wav", fx))
+		if err := os.WriteFile(path, wavBytes(synth(effectSegs[fx])), 0o644); err != nil {
+			os.RemoveAll(dir)
+			return nullEngine{}
+		}
+		e.files[fx] = path
+	}
+	return e
+}
+
+// Play spawns pw-play detached; process reaped asynchronously
+func (e *pwEngine) Play(fx Effect) {
+	if fx == EffectNone || fx >= EffectCount || e.files[fx] == "" {
+		return
+	}
+	cmd := exec.Command("pw-play", "--volume", "0.7", e.files[fx])
+	if err := cmd.Start(); err == nil {
+		go cmd.Wait()
+	}
+}
+
+func (e *pwEngine) Close() {
+	os.RemoveAll(e.dir)
+}
@@ -0,0 +1,81 @@
+package audio
+
+import (
+	"bytes"
+	"encoding/binary"
+	"math"
+)
+
+const sampleRate = 48000 // PipeWire native rate
+
+// seg is one tone segment: linear frequency sweep with pluck envelope
+type seg struct {
+	f0, f1 float64 // Hz
+	dur    float64 // seconds
+	amp    float64 // 0..1
+	square bool
+}
+
+// effectSegs defines each effect's tone sequence — the tuning surface
+var effectSegs = [EffectCount][]seg{
+	EffectPickup:      {{988, 988, 0.055, 0.5, false}, {1319, 1319, 0.11, 0.5, false}},   // B5→E6 coin
+	EffectMagnet:      {{523, 1319, 0.10, 0.45, false}, {784, 1976, 0.16, 0.4, false}},   // rising double sweep — reads as a suction, distinct from the coin
+	EffectShield:      {{659, 988, 0.07, 0.45, false}, {1319, 1319, 0.16, 0.40, false}},  // chime up into a held tone — armor
+	EffectShieldBreak: {{1200, 300, 0.06, 0.50, true}, {700, 180, 0.14, 0.45, true}},     // square shatter; brighter and shorter than the death crunch
+	EffectBoost:       {{392, 1568, 0.16, 0.50, false}, {1568, 1568, 0.10, 0.35, false}}, // fast sweep up — tempo kick
+	EffectDeflect:     {{1200, 1600, 0.025, 0.20, true}, {1600, 900, 0.035, 0.15, true}}, // fires once per walled chord traversed under a Boost — short, dry, low
+	EffectMoveRow:     {{300, 620, 0.07, 0.35, false}},                                   // whoosh up
+	EffectMoveLane:    {{440, 470, 0.04, 0.28, false}},                                   // tick
+	EffectHitWall:     {{140, 50, 0.30, 0.6, true}},                                      // crunch drop
+	EffectLevelClear: { // C-major arpeggio
+		{523, 523, 0.09, 0.45, false},
+		{659, 659, 0.09, 0.45, false},
+		{784, 784, 0.09, 0.45, false},
+		{1047, 1047, 0.18, 0.45, false},
+	},
+}
+
+// synth renders segments to 16-bit mono PCM
+func synth(segs []seg) []int16 {
+	var out []int16
+	for _, s := range segs {
+		n := int(s.dur * sampleRate)
+		phase := 0.0
+		for i := range n {
+			t := float64(i) / float64(n)
+			f := s.f0 + (s.f1-s.f0)*t
+			phase += 2 * math.Pi * f / sampleRate
+			v := math.Sin(phase)
+			if s.square {
+				if v >= 0 {
+					v = 1
+				} else {
+					v = -1
+				}
+			}
+			env := math.Min(t*24, 1) * math.Exp(-4.2*t) // fast attack, pluck decay
+			out = append(out, int16(v*env*s.amp*32767))
+		}
+	}
+	return out
+}
+
+// wavBytes wraps PCM in a minimal RIFF/WAVE container (PCM16 mono)
+func wavBytes(samples []int16) []byte {
+	var b bytes.Buffer
+	dataLen := uint32(len(samples) * 2)
+	b.WriteString("RIFF")
+	binary.Write(&b, binary.LittleEndian, 36+dataLen)
+	b.WriteString("WAVEfmt ")
+	binary.Write(&b, binary.LittleEndian, uint32(16))
+	binary.Write(&b, binary.LittleEndian, uint16(1)) // PCM
+	binary.Write(&b, binary.LittleEndian, uint16(1)) // mono
+	binary.Write(&b, binary.LittleEndian, uint32(sampleRate))
+	binary.Write(&b, binary.LittleEndian, uint32(sampleRate*2)) // byte rate
+	binary.Write(&b, binary.LittleEndian, uint16(2))            // block align
+	binary.Write(&b, binary.LittleEndian, uint16(16))           // bits/sample
+	b.WriteString("data")
+	binary.Write(&b, binary.LittleEndian, dataLen)
+	binary.Write(&b, binary.LittleEndian, samples)
+	return b.Bytes()
+}
@@ -0,0 +1,91 @@
+//go:build linux
+
+package main
+
+import (
+	"time"
+
+	rl "github.com/gen2brain/raylib-go/raylib"
+
+	"symph/audio"
+	"symph/game"
+	"symph/input"
+	raylibrender "symph/render/raylib"
+)
+
+const (
+	defaultScreenW = 800
+	defaultScreenH = 600
+)
+
+func main() {
+	rl.SetConfigFlags(rl.FlagWindowResizable | rl.FlagVsyncHint)
+	rl.InitWindow(defaultScreenW, defaultScreenH, "Symph")
+	defer rl.CloseWindow()
+
+	rl.SetTargetFPS(60)
+
+	state := game.New()
+	sfx := audio.NewMuter(audio.NewEngine())
+	defer sfx.Close()
+	renderer := raylibrender.NewRenderer(state)
+
+	for !rl.WindowShouldClose() {
+		now := time.Now()
+
+		// Modifier state is polled, not queued
+		ctrl := rl.IsKeyDown(rl.KeyLeftControl) || rl.IsKeyDown(rl.KeyRightControl)
+
+		for {
+			k := rl.GetKeyPressed()
+			if k == 0 {
+				break
+			}
+			if k == rl.KeyS && ctrl {
+				renderer.Muted = sfx.Toggle()
+				continue
+			}
+			if ik := keyFromRaylib(k); ik != input.KeyNone {
+				state.Dispatch(input.Translate(ik), now)
+			}
+		}
+
+		state.Update(now)
+		for _, ge := range state.DrainEvents() {
+			sfx.Play(audio.MapGameEvent(ge))
+		}
+
+		rl.BeginDrawing()
+		renderer.Draw(int32(rl.GetScreenWidth()), int32(rl.GetScreenHeight()), now)
+		rl.EndDrawing()
+	}
+}
+
+// keyFromRaylib translates a raylib keycode to a platform-neutral input.Key
+func keyFromRaylib(k int32) input.Key {
+	switch k {
+	case rl.KeyH:
+		return input.KeyH
+	case rl.KeyJ:
+		return input.KeyJ
+	case rl.KeyK:
+		return input.KeyK
+	case rl.KeyL:
+		return input.KeyL
+	case rl.KeySemicolon:
+		return input.KeySemicolon
+	case rl.KeyA:
+		return input.KeyA
+	case rl.KeyS:
+		return input.KeyS
+	case rl.KeyD:
+		return input.KeyD
+	case rl.KeyF:
+		return input.KeyF
+	case rl.KeySpace:
+		return input.KeySpace
+	case rl.KeyEnter, rl.KeyKpEnter:
+		return input.KeyEnter
+	}
+	return input.KeyNone
+}
@@ -0,0 +1,140 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"time"
+
+	"symph/audio"
+	"symph/game"
+	"symph/input"
+	"symph/parameter"
+	"symph/render"
+
+	"github.com/lixenwraith/terminal"
+)
+
+func main() {
+
+	// Terminal init
+	term := terminal.New()
+	if err := term.Init(); err != nil {
+		fmt.Fprintln(os.Stderr, "terminal init:", err)
+		os.Exit(1)
+	}
+	defer term.Fini()
+
+	// Game init
+	state := game.New()
+
+	// Audio init (silent fallback when backend unavailable)
+	sfx := audio.NewMuter(audio.NewEngine())
+	defer sfx.Close()
+
+	// Render init
+	width, height := term.Size()
+	renderer := render.NewRenderer(term, width, height, state)
+	minW, minH := render.MinSize()
+
+	// Ticker wakes the event loop for UI frames (~60fps)
+	// The engine strictly owns beat quantization via Update(); frontend just pushes time forward
+	ticker := time.NewTicker(parameter.GameRenderUpdate)
+	defer ticker.Stop()
+
+	go func() {
+		for range ticker.C {
+			term.PostEvent(terminal.Event{Type: terminal.EventKey, Key: terminal.KeyNone})
+		}
+	}()
+
+	renderer.Render(time.Now())
+
+	for {
+
+		ev := term.PollEvent()
+
+		switch ev.Type {
+
+		case terminal.EventClosed, terminal.EventError:
+			return
+
+		case terminal.EventKey:
+
+			// Quit on Escape, Ctrl+C, or 'q'
+			if ev.Key == terminal.KeyEscape || ev.Key == terminal.KeyCtrlC || ev.Rune == 'q' || ev.Rune == 'Q' {
+				return
+			}
+
+			// Toggle mute with Ctrl+S
+			if ev.Key == terminal.KeyCtrlS {
+				renderer.Muted = sfx.Toggle()
+			}
+
+			now := time.Now()
+
+			// Viewport gate. Below the minimum the field is unrenderable;
+			// freeze the simulation clock so no beats elapse behind the notice
+			if w, h := term.Size(); w < minW || h < minH {
+				state.Pause(now)
+				renderer.Render(now)
+				continue
+			}
+			state.Resume(now)
+
+			// Real key: translate and dispatch with strict temporal timestamp
+			if k := eventToKey(ev); k != input.KeyNone {
+				state.Dispatch(input.Translate(k), now)
+			}
+
+			// Engine time step, event drain, render cycle every iteration
+			// (Synthetic tick falls through to here naturally)
+			state.Update(now)
+			for _, ge := range state.DrainEvents() {
+				sfx.Play(audio.MapGameEvent(ge))
+			}
+			renderer.Render(now)
+
+		case terminal.EventResize:
+
+			renderer.Resize(ev.Width, ev.Height)
+			now := time.Now()
+			if ev.Width < minW || ev.Height < minH {
+				state.Pause(now)
+			} else {
+				state.Resume(now)
+			}
+			renderer.Render(time.Now())
+
+		}
+	}
+}
+
+// eventToKey translates a terminal key event to a platform-neutral input.Key
+func eventToKey(ev terminal.Event) input.Key {
+	if ev.Key == terminal.KeyEnter {
+		return input.KeyEnter
+	}
+	switch ev.Rune {
+	case 'h', 'H':
+		return input.KeyH
+	case 'j', 'J':
+		return input.KeyJ
+	case 'k', 'K':
+		return input.KeyK
+	case 'l', 'L':
+		return input.KeyL
+	case ';':
+		return input.KeySemicolon
+	case 'a', 'A':
+		return input.KeyA
+	case 's', 'S':
+		return input.KeyS
+	case 'd', 'D':
+		return input.KeyD
+	case 'f', 'F':
+		return input.KeyF
+	case ' ':
+		return input.KeySpace
+	}
+	return input.KeyNone
+}
@@ -0,0 +1,239 @@
+# Symph: Architecture & Design Specification
+
+## System Abstract
+
+Symph is a rhythm-driven grid traversal game. Real-time spatial mechanics are
+synchronized against a quantized temporal progression. The engine decouples
+hardware-frequency rendering and input polling from macro-frequency musical
+progression, exposing a deterministic, side-effect-free state machine to
+Terminal, Raylib, and Mobile frontends.
+
+---
+
+## 1. Domain Nomenclature
+
+* **Symphony** *(planned)*: collection of Songs.
+* **Song**: master temporal container (Z-axis). Slice of `Chord`.
+* **Chord**: one slice in time. A 3x3 matrix of `Note`.
+* **Note**: atomic element at `(Y, X)`, carrying a `Value`.
+* **Symphace** *(planned)*: bounded environment surrounding the grid.
+
+---
+
+## 2. Coordinate System & Displacement
+
+* **PIZ**: temporal depth index. Advances on the beat.
+* **PIY, PIX**: grid coordinates, bounded to `[0, 2]`. Spawn/rest anchor `(1, 1)`.
+
+Movement is decoupled from `PIZ`.
+
+* **X (lanes)**: persistent. The player holds the lane until moved again.
+* **Y (rows)**: transient. A row shift arms `ResetTime` at
+  `PlayerRowResetChords * PlayDeltaZ`, rescaled on every tempo change, so the
+  landing chord is invariant across levels and across a Boost. On expiry, Y
+  collapses to `BaseIndexY` and the landing cell is resolved — returning into a
+  wall is fatal.
+  A manual move back to the base row cancels the timer (duck out of a jump).
+* Cells resolve on three triggers: beat arrival, player movement, row-reset
+  landing.
+
+---
+
+## 3. Phases
+
+`PhasePlaying` → `PhaseLevelClear` (song exhausted, `TransitionDuration`
+interlude, then next level) → `PhasePlaying`.
+`PhaseGameOver` on wall contact; `ActionConfirm` restarts from level 1.
+Input is inert during `PhaseLevelClear`. `Pause`/`Resume` shift every absolute
+timestamp forward by the paused span, so no beats or row-reset expiries
+accumulate behind a pause (used by the terminal viewport gate).
+A deadline already lapsed when the dead span opened is cleared, not shifted:
+dead time never revives a Boost, extends a row reset, or replays a burn-out.
+
+---
+
+## 4. Chronometry & Concurrency
+
+Two isolated time domains:
+
+* **Macro (beat)**: `PlayDeltaZ`. Elapsed spans are consumed in whole ticks;
+  `LastPlayedTime` advances by whole intervals, never by `now` — no drift.
+* **Micro (render/input)**: host framerate (`GameRenderUpdate`, ~60Hz).
+  Resolves sub-beat state: row-reset countdown, blink phase, morph colors.
+
+### Tempo
+
+* `BaseDeltaZ` — level-derived: `GameDeltaZBase` (500ms), shortened by
+  `GameDeltaZStep` per level down to `GameDeltaZMin`.
+* `deltaAt(t)` — `BaseDeltaZ / BoostSpeedFactor` while a Boost runs at `t`, else
+  `BaseDeltaZ`. The only place tempo is scaled; a slow effect divides here.
+* `PlayDeltaZ` — the interval of the beat **in flight**, fixed at that beat's
+  start. A Boost taken mid-chord lands on the next boundary: the chord under the
+  player never shortens beneath them.
+* `Update` re-reads the interval at each boundary, so a Boost expiring inside a
+  frame is exact. `TimeToChordDistance` replays the recurrence forward, so every
+  displayed countdown matches the simulation.
+
+### Pipeline
+
+Single-threaded polling loop. No mutexes, no channels over game state.
+
+* A `time.Ticker` injects synthetic wake-up events (`terminal.KeyNone`) into
+  the frontend event queue; raylib polls its own frame loop.
+* Per iteration: translate native key → `input.Key` → `game.Action`,
+  `Dispatch(action, now)`, `Update(now)`, `DrainEvents()`, render.
+* Host controls bypass `input`/`game`: quit (Esc / Ctrl+C / `q`) and the audio
+  gate (Ctrl+S) are handled in `cmd/`. They must work while paused and in every
+  phase, which `Dispatch` does not allow. `audio.Muter` wraps an `Engine` and
+  drops `Play` while muted; the header carries `MUTE`.
+* The engine emits no side-effects. Gameplay occurrences are queued as `Event`
+  enums and drained once per iteration by the frontend, which maps them to
+  audio.
+
+---
+
+## 5. Values & Items
+
+Every `Value` has one row in `types.valueSpecs` — `{Name, Glyph, Polarity}` —
+which is the single source of truth for kind identity. `Glyph` is the pattern
+authoring rune *and* the ASCII display fallback; `init` asserts completeness,
+ASCII range and uniqueness at process start. `Polarity` is a table lookup, not
+a switch.
+
+| Value | Glyph | Polarity | Behavior |
+|---|---|---|---|
+| `ValueEnergy` | `*` | positive | +1 energy, consumed on contact |
+| `ValueMagnet` | `M` | positive | consumed; sweeps **every** Energy note within `PositionLookaheadWindow` chords, at all 9 grid positions |
+| `ValueShield` | `S` | positive | consumed; arms `ShieldCharges` absorb charges. No expiry |
+| `ValueBoost`  | `B` | positive | consumed; arms `BoostDuration` of `BoostSpeedFactor`× tempo. Refreshes, does not stack |
+| `ValueWall`   | `#` | negative | fatal, unless a charge absorbs it |
+
+Adding a kind is three rows: `types.valueSpecs` (identity),
+`game.resolvers` (contact behavior), `render.valueVisuals` (color ramp).
+No switch is edited. `parseChord` rejects any pattern authoring a kind with no
+resolver, so an unresolved kind can never be walked through.
+
+### 5.1 Status
+
+`game.Status` holds the persistent player effects. Both survive a level change;
+both are cleared on restart, never on death-free level transition.
+
+* **Shield** — a charge count. `hitHazard` spends one charge, **destroys the
+  note**, records it in the consume ring, and play continues: the lookahead,
+  ring and timer all re-derive from the cleared cell, giving the player exactly
+  one beat to leave the lane. Because absorption sits in `resolveCell`, it
+  covers all three resolution triggers (beat arrival, movement, row-reset
+  landing) with no second code path.
+* **Boost** — an absolute deadline. Read only at beat boundaries.
+
+`Status.shift(at, d)` moves **live** deadlines across a pause and across the
+level-clear interlude, so a Boost taken at a song's tail is not burned by the
+transition wave. `at` is the instant the dead span opened; a deadline already
+lapsed at `at` is cleared, never revived. `restart` zeroes the whole `Status`.
+
+---
+
+## 6. Lookahead Model
+
+`ScanTile(y, x, window)` returns a `TileLookahead` for one grid position,
+allocation-free, in a single pass:
+
+* `Cells` — raw `Value` per chord distance (0 = current chord).
+* `WallMask` — `uint16` bitmask, bit *d* set when distance *d* holds a wall.
+  `TileLookaheadMaxWindow` = 16 is the hard ceiling on the window.
+* `Positive` / `Negative` — nearest occurrence per polarity class.
+* `NearestWall()` derives the leading wall segment (distance, run length,
+  reopen gap, trap flag, open-ended flag) from the bitmask.
+
+All proximity, run, gap and trap **policy** derives from the bitmask in the
+frontend. The engine holds no presentation rules.
+
+---
+
+## 7. Presentation Contract (terminal)
+
+Tile, 12x5:
+
+* **border** — ring colored by nearest-wall band (`WallBandCount` bands of
+  `WallBandSize` chords). Fill is binary: solid only when a wall occupies the
+  current chord. Urgency rides on color, not density.
+* **header row** — `LEVEL` left, active status (shield glyph, boost countdown)
+  centered, `ENERGY` right.
+* **row 1** — wall timer. `▼` chords until the lane shuts, `▲` until it
+  reopens; `+` open-ended run, `!` trap gap (`<= TrapGapMax`).
+* **row 2** — distance row: nearest positive and nearest negative occurrence,
+  each glyph + chord-distance. The tile(s) whose distance equals the
+  **grid-wide** minimum for that polarity blink their group
+  (positive: white/green, negative: yellow/red, `RenderBlinkPeriod`). Ties are
+  not broken — every tile at the minimum blinks. Distance 0 counts.
+* **row 3** — lookahead strip: one cell per chord, leftmost = now.
+  Distance is carried positionally, so items draw at arrived color;
+  walls keep the band gradient so ring, timer and strip agree.
+  A cell emptied by consumption burns out in place: 
+  white flash, then glyph collapse into the rail cell.
+  Grid-scope scan (`render.GridScan`) and the burn-out projection
+  (`render.FadeGrid`) are shared by both frontends; policy lives in `render`.
+* **background** — player position fill; brightened while a charge is held, so
+  the shield reads in the field rather than only in the HUD.
+
+Item color ramps use high-luminance endpoints at both ends: the distance row
+draws items at their true distance, and a dark distant endpoint is unreadable
+against the black field.
+
+**Raylib**: same contract, different medium. Layout derives from two gap
+fractions — `gapFracX` (usable width) and `gapFracY` (tile height). The row gap
+hosts the reset funnel, so the funnel font is sized against it (`funnelFrac`,
+floored at `funnelFontMin`).
+
+---
+
+## 8. Package Topology
+
+Unidirectional dependency flow (supports CGO/gomobile).
+
+* `types/` — dependency-free structures (`Song`, `Chord`, `Note`,
+  `PlayerState`) and the value registry (`valueSpecs`: identity, glyph,
+  polarity). Breaks import cycles.
+* `parameter/` — compile-time constants: grid bounds, timings, glyphs, tile
+  geometry, lookahead window. Several invariants are enforced by `const _`
+  assertions (window vs bitmask width, window vs band span, density glyphs vs
+  band count).
+* `game/` — pure state engine. Contact behavior is the `resolvers` table keyed
+  on `Value`; `Status` holds persistent item effects.
+* `input/` — native key → platform-neutral `Key` → `game.Action`. The
+  gomobile path bypasses this package and produces `Action` directly.
+* `render/` — appearance is the `valueVisuals` table keyed on `Value`.
+  `TileGlyphASCII` is the atlas-limited substitution for raylib.
+  `render/raylib/` shares the `render` caching pipeline and is up-to-date with the `TileLookahead` API.
+* `audio/` — fire-and-forget effects. PCM synthesized at startup; PipeWire
+  backend on Linux, silent `nullEngine` elsewhere or when `pw-play` is absent.
+  `Muter` composes an `Engine` with the host mute gate.
+* `cmd/` — hosts (`symph-term`, `symph-raylib`): wiring, event poller, ticker.
+
+---
+
+## 9. Known Divergences
+
+* Raylib substitutes ASCII for the Unicode glyph set (default font atlas is
+   32..126) and draws walls as rectangles rather than density glyphs.
+   Load a font with an explicit codepoint set for glyph parity.
+* `audio` spawns one `pw-play` process per effect; per-spawn stream connect
+  costs tens of ms. Replace with a persistent stream before latency matters.
+* FreeBSD audio backend (sndio/OSS) unimplemented — falls through to
+  `nullEngine`.
+* **Boost expiry inside a wall band is the primary death mode.** `resolveCell`
+  fires on beat arrival, so a boosted player standing in a wall when the
+  deadline lapses dies on the next beat — one chord (>= 150ms) to leave the
+  lane. The HUD blink is the only warning. Intentional.
+* **Walls still render lethal while boosted.** Ring, timer and strip are
+  unaware of immunity; recoloring requires threading `Status` through
+  `WallBandColor` / `TileGlyph` / `WallTimerText`. Deferred.
+* **Boost shares the warm end of the wall band palette** (`PaleLemon → Gold` vs
+  `Yellow → BrightRed`). Glyph and fixed distance-row column disambiguate.
+* `EventDeflect` fires once per walled chord traversed; with the `pw-play`
+  backend that is one process spawn per chord during a boosted wall run.
+* `ItemFadeDuration` (140ms) clears the boosted beat floor
+  (`GameDeltaZMin/BoostSpeedFactor` = 150ms) by 10ms. Lower it to ~100ms before
+  touching either constant.
+* `TimerText` clamps at 9.9s, so a fresh 10s Boost reads `9.9` for its first
+  100ms.
@@ -0,0 +1,54 @@
+package game
+
+import (
+	"time"
+)
+
+// Action is a platform-neutral semantic input action, dispatched to the
+// engine independent of the originating input device (keyboard, touch, etc)
+type Action uint8
+
+const (
+	ActionNone      Action = iota
+	ActionMoveLeft         // grid: dx=-1
+	ActionMoveUp           // grid: dy=-1
+	ActionMoveDown         // grid: dy=+1
+	ActionMoveRight        // grid: dx=+1
+
+	// Reserved, behavior defined later
+	ActionStubSemicolon
+	ActionStubA
+	ActionStubS
+	ActionStubD
+	ActionStubF
+	ActionSpace
+	ActionConfirm
+)
+
+// Dispatch applies a single Action to the game state, gated by phase.
+// Requires current time to timestamp temporal state shifts
+func (gs *GameState) Dispatch(a Action, now time.Time) {
+	if gs.Paused {
+		return
+	}
+	switch gs.Phase {
+	case PhaseGameOver:
+		if a == ActionConfirm {
+			gs.restart(now)
+		}
+		return
+	case PhaseLevelClear:
+		return // input inert during transition
+	}
+
+	switch a {
+	case ActionMoveLeft:
+		gs.MovePlayer(0, -1, now)
+	case ActionMoveUp:
+		gs.MovePlayer(-1, 0, now)
+	case ActionMoveDown:
+		gs.MovePlayer(1, 0, now)
+	case ActionMoveRight:
+		gs.MovePlayer(0, 1, now)
+	}
+}
@@ -0,0 +1,563 @@
+package game
+
+import (
+	"math/bits"
+	"time"
+
+	"symph/parameter"
+	"symph/types"
+)
+
+// --- State machine ---
+
+// Phase is the top-level game state machine
+type Phase uint8
+
+const (
+	PhasePlaying    Phase = iota
+	PhaseLevelClear       // song finished, transition interlude running
+	PhaseGameOver         // wall hit, awaiting ActionConfirm restart
+)
+
+// Event is a gameplay occurrence emitted for frontend consumption (audio,
+// haptics). The engine performs no side-effects itself
+type Event uint8
+
+const (
+	EventNone Event = iota
+	EventPickup
+	EventMagnet
+	EventShield
+	EventBoost
+	EventDeflect
+	EventShieldBreak
+	EventHitWall
+	EventMoveRow
+	EventMoveLane
+	EventLevelClear
+	EventLevelStart
+)
+
+// GameState represents the complete game state
+type GameState struct {
+	Song              types.Song        // All chords in the song
+	LastPlayedTime    time.Time         // When we last played a note
+	PlayerState       types.PlayerState // Current player position
+	BaseDeltaZ        time.Duration     // Level-derived inter-chord interval
+	PlayDeltaZ        time.Duration     // Interval of the beat in flight, fixed at its start
+	CurrentPlayIndexZ int               // Current play index (which chord we're on)
+
+	Phase      Phase
+	PhaseStart time.Time // Entry time of current phase; drives transition timing/FX
+	Level      int
+	Energy     int
+	Status     Status // Persistent item effects; survives a level change
+
+	events []Event
+
+	// consumed-note ring; frontends animate the burn-out from it
+	consumed  [parameter.ConsumeRingSize]Consume
+	consumeAt int
+
+	Paused   bool
+	pausedAt time.Time
+}
+
+// Consume records a positive note removed from the field in absolute song coordinates.
+// The frontend is responsible for defining the duration and appearance of the burn-out.
+type Consume struct {
+	At    time.Time
+	Z     int         // absolute chord index
+	Y, X  int         // grid position
+	Value types.Value // ValueNone marks an unused ring slot
+}
+
+// --- Lifecycle ---
+
+// New creates a game state and starts level 1
+func New() *GameState {
+	gs := &GameState{}
+	gs.startLevel(1, time.Now())
+	return gs
+}
+
+// recordConsume writes into the ring, overwriting the oldest entry
+func (gs *GameState) recordConsume(v types.Value, z, y, x int, now time.Time) {
+	gs.consumed[gs.consumeAt] = Consume{At: now, Z: z, Y: y, X: x, Value: v}
+	gs.consumeAt = (gs.consumeAt + 1) % len(gs.consumed)
+}
+
+// Consumed exposes the ring for frontend burn-out projection. Slots with ValueNone are unused.
+// The backing array is overwritten in place; callers must not retain the slice across iterations
+func (gs *GameState) Consumed() []Consume { return gs.consumed[:] }
+
+// Pause freezes the simulation clock. Idempotent
+func (gs *GameState) Pause(now time.Time) {
+	if gs.Paused {
+		return
+	}
+	gs.Paused, gs.pausedAt = true, now
+}
+
+// Resume shifts every absolute timestamp forward by the paused span, so no
+// beats or row-reset expiries accumulate behind the pause. Idempotent
+func (gs *GameState) Resume(now time.Time) {
+	if !gs.Paused {
+		return
+	}
+	d := max(now.Sub(gs.pausedAt), 0)
+	gs.LastPlayedTime = gs.LastPlayedTime.Add(d)
+	gs.PhaseStart = gs.PhaseStart.Add(d)
+	// Deadlines lapsed before the freeze are cleared, not carried forward
+	gs.Status.shift(gs.pausedAt, d)
+	if gs.PlayerState.ResetTime.After(gs.pausedAt) {
+		gs.PlayerState.ResetTime = gs.PlayerState.ResetTime.Add(d)
+	}
+	for i := range gs.consumed {
+		c := &gs.consumed[i]
+		if c.Value == types.ValueNone {
+			continue
+		}
+		// Burn-out finished before the freeze must not replay
+		if gs.pausedAt.Sub(c.At) >= parameter.ItemFadeDuration {
+			c.Value = types.ValueNone
+			continue
+		}
+		c.At = c.At.Add(d)
+	}
+	gs.Paused = false
+}
+
+// startLevel (re)initializes song, player, and timing for the given level.
+// Status is deliberately untouched: item effects cross the level boundary
+func (gs *GameState) startLevel(level int, now time.Time) {
+	gs.Level = level
+	gs.Song = *newSong(level)
+	gs.CurrentPlayIndexZ = 0
+	gs.consumed, gs.consumeAt = [parameter.ConsumeRingSize]Consume{}, 0
+	gs.PlayerState = types.PlayerState{
+		PlayIndexY: parameter.GamePlayIndexYStart,
+		PlayIndexX: parameter.GamePlayIndexXStart,
+		BaseIndexY: parameter.GamePlayIndexYStart,
+	}
+	gs.BaseDeltaZ = max(
+		parameter.GameDeltaZBase-time.Duration(level-1)*parameter.GameDeltaZStep,
+		parameter.GameDeltaZMin,
+	)
+	gs.LastPlayedTime = now
+	gs.PlayDeltaZ = gs.deltaAt(now)
+	gs.PhaseStart = now
+	gs.Phase = PhasePlaying
+	gs.emit(EventLevelStart)
+}
+
+// deltaAt returns the inter-chord interval for a beat starting at t: the
+// level-derived base, divided by BoostSpeedFactor while a Boost is active.
+// Update and TimeToChordDistance share this recurrence, so every displayed
+// countdown matches the simulation exactly, including across a Boost expiry
+func (gs *GameState) deltaAt(t time.Time) time.Duration {
+	d := gs.BaseDeltaZ
+	if gs.Status.Boosted(t) {
+		d /= parameter.BoostSpeedFactor
+	}
+	return d
+}
+
+// rescaleReset holds a pending row displacement at a fixed chord length across
+// a tempo change: the remaining span is scaled by the interval ratio, so a jump
+// armed for PlayerRowResetChords chords lands PlayerRowResetChords chords later
+// whatever the Boost does in between. Called only at beat boundaries, so the
+// beat domain and the displacement domain run off one clock.
+// rem <= PlayerRowResetChords*GameDeltaZBase; the product cannot overflow int64
+func (gs *GameState) rescaleReset(at time.Time, oldD, newD time.Duration) {
+	if oldD == newD || gs.PlayerState.ResetTime.IsZero() {
+		return
+	}
+	rem := gs.PlayerState.ResetTime.Sub(at)
+	if rem <= 0 {
+		return
+	}
+	gs.PlayerState.ResetTime = at.Add(rem * newD / oldD)
+}
+
+// restart resets progression after game over
+func (gs *GameState) restart(now time.Time) {
+	gs.Energy = 0
+	gs.Status = Status{} // Reset effects on game restart
+	gs.startLevel(1, now)
+}
+
+// --- Simulation ---
+
+// Update advances time-based game state
+func (gs *GameState) Update(now time.Time) {
+	if gs.Paused {
+		return
+	}
+	switch gs.Phase {
+	case PhaseLevelClear:
+		if el := now.Sub(gs.PhaseStart); el >= parameter.TransitionDuration {
+			// The interlude is dead time — hold the effect deadlines across it
+			gs.Status.shift(gs.PhaseStart, el) // Clamp at the interlude entry
+			gs.startLevel(gs.Level+1, now)
+		}
+		return
+	case PhaseGameOver:
+		return
+	}
+
+	// 1. Row displacement expiry (sub-beat domain): collapse Y to base row.
+	// Landing resolves against the current chord — returning into a wall kills
+	if !gs.PlayerState.ResetTime.IsZero() && now.After(gs.PlayerState.ResetTime) {
+		gs.PlayerState.PlayIndexY = gs.PlayerState.BaseIndexY
+		gs.PlayerState.ResetTime = time.Time{}
+		gs.resolveCell(now)
+		if gs.Phase != PhasePlaying {
+			return
+		}
+	}
+
+	// 2. Song ticks (beat domain).
+	// One beat at a time. The interval is fixed at each beat's start, so a
+	// Boost taken mid-chord lands on the next boundary (the chord in flight
+	// never shortens under the player) and an expiry inside a frame is exact.
+	// LastPlayedTime advances only by whole intervals — no drift
+	for {
+		next := gs.LastPlayedTime.Add(gs.PlayDeltaZ)
+		if now.Before(next) {
+			return
+		}
+		if gs.CurrentPlayIndexZ >= len(gs.Song.Chords)-1 {
+			gs.Phase = PhaseLevelClear
+			gs.PhaseStart = now
+			gs.emit(EventLevelClear)
+			return
+		}
+		gs.LastPlayedTime = next
+
+		// Tempo transitions land on beat boundaries only; a pending row
+		// displacement is rescaled with them
+		d := gs.deltaAt(next)
+		gs.rescaleReset(next, gs.PlayDeltaZ, d)
+		gs.PlayDeltaZ = d
+
+		gs.CurrentPlayIndexZ++
+		gs.resolveCell(now)
+		if gs.Phase != PhasePlaying {
+			return
+		}
+	}
+}
+
+// resolver applies a Value's contact behavior. n aliases the note inside the
+// Song: consumption writes through it
+type resolver func(gs *GameState, n *types.Note, z, y, x int, now time.Time)
+
+// resolvers is indexed by Value. A nil row is inert — the kind renders and
+// carries polarity, but contact does nothing. Adding a kind means adding a row
+// here and a row in types.valueSpecs. The generator rejects patterns that
+// author an unresolved kind, so inertness is never reachable in play
+var resolvers = [types.ValueCount]resolver{
+	types.ValueEnergy: (*GameState).takeEnergy,
+	types.ValueMagnet: (*GameState).takeMagnet,
+	types.ValueShield: (*GameState).takeShield,
+	types.ValueBoost:  (*GameState).takeBoost,
+	types.ValueWall:   (*GameState).hitHazard,
+}
+
+// resolveCell evaluates content at the player position of the current chord.
+// Called on beat arrival, on player movement, and on row-reset landing — so
+// Shield absorption covers all three without a second code path
+func (gs *GameState) resolveCell(now time.Time) {
+	y, x, z := gs.PlayerState.PlayIndexY, gs.PlayerState.PlayIndexX, gs.CurrentPlayIndexZ
+	n := &gs.Song.Chords[z].Notes[y][x]
+	if r := resolvers[n.Value]; r != nil {
+		r(gs, n, z, y, x, now)
+	}
+}
+
+func (gs *GameState) takeEnergy(n *types.Note, z, y, x int, now time.Time) {
+	gs.Energy++
+	n.Value = types.ValueNone
+	gs.recordConsume(types.ValueEnergy, z, y, x, now)
+	gs.emit(EventPickup)
+}
+
+// takeMagnet sweeps every Energy note inside the lookahead window at every grid
+// position — the collected set is exactly what the tile strips display
+func (gs *GameState) takeMagnet(n *types.Note, z, y, x int, now time.Time) {
+	n.Value = types.ValueNone
+	gs.recordConsume(types.ValueMagnet, z, y, x, now)
+	gs.collectWindow(parameter.PositionLookaheadWindow, now)
+	gs.emit(EventMagnet)
+}
+
+// takeShield arms the absorb charge. A pickup while shielded re-arms and is
+// still consumed
+func (gs *GameState) takeShield(n *types.Note, z, y, x int, now time.Time) {
+	gs.Status.grantShield()
+	n.Value = types.ValueNone
+	gs.recordConsume(types.ValueShield, z, y, x, now)
+	gs.emit(EventShield)
+}
+
+// takeBoost re-arms the tempo deadline. The beat in flight keeps the interval
+// it started with; the shortened interval applies from the next boundary
+func (gs *GameState) takeBoost(n *types.Note, z, y, x int, now time.Time) {
+	gs.Status.grantBoost(now)
+	n.Value = types.ValueNone
+	gs.recordConsume(types.ValueBoost, z, y, x, now)
+	gs.emit(EventBoost)
+}
+
+// hitHazard resolves contact with a negative Value. Precedence:
+//
+//	Boost   — immune. The note survives: the field, ring, timer and lookahead
+//	          stay truthful, and no charge is spent
+//	Shield  — one charge absorbs the contact and destroys the note. Play
+//	          continues; everything re-derives from the cleared cell, giving the
+//	          player one beat to leave the lane
+//	neither — the run ends
+//
+// Non-fatal negatives (Drain) branch here once implemented
+func (gs *GameState) hitHazard(n *types.Note, z, y, x int, now time.Time) {
+	if gs.Status.Boosted(now) {
+		gs.emit(EventDeflect)
+		return
+	}
+	if gs.Status.absorb() {
+		v := n.Value
+		n.Value = types.ValueNone
+		gs.recordConsume(v, z, y, x, now)
+		gs.emit(EventShieldBreak)
+		return
+	}
+	gs.Phase = PhaseGameOver
+	gs.PhaseStart = now
+	gs.emit(EventHitWall)
+}
+
+// MovePlayer applies a grid delta. Lane (X) shifts persist; row (Y) shifts
+// arm the return-to-base-row timer. Manual return to base row cancels the
+// timer (duck out of a jump). Movement into content resolves immediately
+func (gs *GameState) MovePlayer(dy, dx int, now time.Time) {
+	p := &gs.PlayerState
+	moved := false
+
+	if dy != 0 {
+		if ny := p.PlayIndexY + dy; ny >= 0 && ny < parameter.GamePlayIndexYMax {
+			p.PlayIndexY = ny
+			moved = true
+			gs.emit(EventMoveRow)
+			if ny == p.BaseIndexY {
+				p.ResetTime = time.Time{}
+			} else {
+				// Based on beat interval in flight. rescaleReset holds the chord length across any tempo change before expiry.
+				p.ResetTime = now.Add(parameter.PlayerRowResetChords * gs.PlayDeltaZ)
+			}
+		}
+	}
+
+	if dx != 0 {
+		if nx := p.PlayIndexX + dx; nx >= 0 && nx < parameter.GamePlayIndexXMax {
+			p.PlayIndexX = nx
+			moved = true
+			gs.emit(EventMoveLane)
+		}
+	}
+
+	if moved {
+		gs.resolveCell(now)
+	}
+}
+
+// --- Event queue ---
+
+// emit queues a gameplay event for frontend drain
+func (gs *GameState) emit(e Event) {
+	gs.events = append(gs.events, e)
+}
+
+// DrainEvents returns and clears queued events. Single consumer: call once per
+// loop iteration from the owning goroutine, consume before next Dispatch/Update
+func (gs *GameState) DrainEvents() []Event {
+	if len(gs.events) == 0 {
+		return nil
+	}
+	evs := gs.events
+	gs.events = nil
+	return evs
+}
+
+// --- Read-only queries (renderer/audio consumption) ---
+
+// GetNoteAtPlayerPosition returns the note at current player position
+func (gs *GameState) GetNoteAtPlayerPosition() types.Note {
+	return gs.Song.Chords[gs.CurrentPlayIndexZ].Notes[gs.PlayerState.PlayIndexY][gs.PlayerState.PlayIndexX]
+}
+
+// TimeToChordDistance converts a chord-distance to wall-clock time remaining.
+// Distance 0 arrived at LastPlayedTime, so its result is <= 0. LastPlayedTime
+// is frozen outside PhasePlaying; callers gate on Phase
+func (gs *GameState) TimeToChordDistance(distance int, now time.Time) time.Duration {
+	t, d := gs.LastPlayedTime, gs.PlayDeltaZ
+	for range distance {
+		t = t.Add(d)
+		d = gs.deltaAt(t)
+	}
+	return t.Sub(now)
+}
+
+// TileLookaheadMaxWindow is the wall bitmask width
+const TileLookaheadMaxWindow = 16
+
+// Compile-time: the scanned window must fit the uint16 wall bitmask
+const _ = uint(TileLookaheadMaxWindow - parameter.PositionLookaheadWindow)
+
+// ItemStat reports the nearest occurrence of one polarity class at a grid
+// position. Occurrence counts are not carried: the strip shows every occurrence positionally
+type ItemStat struct {
+	Value    types.Value // kind of the nearest occurrence
+	Distance int         // chords to it; -1 when absent
+}
+
+// TileLookahead summarizes one grid position over the observation window.
+// Walls are exposed as a raw bitmask; all proximity/run/gap policy derives
+// from it, keeping presentation rules out of the engine
+type TileLookahead struct {
+	// Cells holds the raw content per chord distance (index 0 = current chord).
+	// Valid for indices < Window
+	Cells [TileLookaheadMaxWindow]types.Value
+
+	WallMask uint16 // bit d set when the chord at distance d holds a wall
+	Window   int    // scanned span; clamped to song end
+
+	// Fixed polarity slots replace the nearest-first kind list
+	Positive ItemStat // nearest Energy/Magnet/Boost/Shield
+	Negative ItemStat // nearest Wall/Spike/Drain/enemy
+}
+
+// WallDistance returns the chord-distance to the nearest wall, -1 if none
+func (tl TileLookahead) WallDistance() int {
+	if tl.WallMask == 0 {
+		return -1
+	}
+	return bits.TrailingZeros16(tl.WallMask)
+}
+
+// WallSegment describes the nearest wall band at a grid position:
+// where it starts, how long it shuts the lane, the reopen gap that follows,
+// and whether that gap is closed again inside the window
+type WallSegment struct {
+	Distance int  // chords until the lane shuts; -1 when no wall in window
+	Run      int  // contiguous walled chords from Distance
+	Gap      int  // open chords after the run
+	Next     bool // another wall closes Gap within the window
+	Open     bool // the run reaches the window edge; Run is a lower bound
+}
+
+// NearestWall resolves the leading wall segment from the bitmask. All
+// proximity/run/gap/trap policy derives from this; the engine holds no
+// presentation rules
+func (tl TileLookahead) NearestWall() WallSegment {
+	if tl.WallMask == 0 {
+		return WallSegment{Distance: -1}
+	}
+	d := bits.TrailingZeros16(tl.WallMask)
+	rest := tl.WallMask >> uint(d) // bit0 set by construction
+
+	seg := WallSegment{Distance: d}
+	seg.Run = min(bits.TrailingZeros16(^rest), tl.Window-d)
+
+	if d+seg.Run >= tl.Window {
+		seg.Open = true
+		return seg
+	}
+	if rest >>= uint(seg.Run); rest == 0 {
+		seg.Gap = tl.Window - d - seg.Run
+		return seg
+	}
+	seg.Gap = bits.TrailingZeros16(rest)
+	seg.Next = true
+	return seg
+}
+
+// WallRun returns the length of the contiguous wall run starting at distance 0
+// (0 when the current chord is open). Equals Window when the run fills the
+// window — the lane's reopen point lies beyond observation
+func (tl TileLookahead) WallRun() int {
+	return min(bits.TrailingZeros16(^tl.WallMask), tl.Window)
+}
+
+// WallGapAfterRun returns the open-chord span following the leading wall run
+// and whether another wall closes that gap within the window
+func (tl TileLookahead) WallGapAfterRun() (gap int, next bool) {
+	run := tl.WallRun()
+	rest := tl.WallMask >> uint(run)
+	if rest == 0 {
+		return tl.Window - run, false
+	}
+	return bits.TrailingZeros16(rest), true
+}
+
+// ScanTile summarizes grid position (y,x) across the specified window of chords
+// starting at CurrentPlayIndexZ (where distance 0 is the current chord).
+func (gs *GameState) ScanTile(y, x, window int) TileLookahead {
+	window = min(window, TileLookaheadMaxWindow)
+
+	// Clamp Window to the chords that exist; run/gap policy reads Window as
+	// the observation horizon
+	if span := len(gs.Song.Chords) - gs.CurrentPlayIndexZ; span < window {
+		window = max(span, 0)
+	}
+
+	tl := TileLookahead{
+		Window:   window,
+		Positive: ItemStat{Distance: -1},
+		Negative: ItemStat{Distance: -1},
+	}
+
+	for d := range window {
+		v := gs.Song.Chords[gs.CurrentPlayIndexZ+d].Notes[y][x].Value
+		tl.Cells[d] = v
+
+		if v == types.ValueWall {
+			tl.WallMask |= 1 << uint(d)
+		}
+
+		switch v.Polarity() {
+		case types.PolarityPositive:
+			if tl.Positive.Distance < 0 {
+				tl.Positive = ItemStat{Value: v, Distance: d}
+			}
+		case types.PolarityNegative:
+			if tl.Negative.Distance < 0 {
+				tl.Negative = ItemStat{Value: v, Distance: d}
+			}
+		}
+	}
+
+	return tl
+}
+
+// --- Legacy queries ---
+
+// collectWindow consumes every Energy note within `window` chords of the
+// current chord, across all grid positions. Walls are untouched: the sweep
+// grants reach, not immunity. One event is emitted by the caller — per-note
+// emission would flood the frontend drain with a burst of identical effects
+func (gs *GameState) collectWindow(window int, now time.Time) {
+	end := min(gs.CurrentPlayIndexZ+window, len(gs.Song.Chords))
+	for z := gs.CurrentPlayIndexZ; z < end; z++ {
+		notes := &gs.Song.Chords[z].Notes
+		for y := range notes {
+			for x := range notes[y] {
+				if notes[y][x].Value == types.ValueEnergy {
+					notes[y][x].Value = types.ValueNone
+					gs.Energy++
+					gs.recordConsume(types.ValueEnergy, z, y, x, now)
+				}
+			}
+		}
+	}
+}
@@ -0,0 +1,258 @@
+package game
+
+import (
+	"fmt"
+	"math/rand/v2"
+	"strings"
+
+	"symph/parameter"
+	"symph/types"
+)
+
+// patternDef is an authored gameplay segment. Patterns are hand-built to stay
+// fair: every chord leaves a reachable safe cell, hazards are telegraphed by
+// preceding pickups. minLevel gates entry into the selection pool
+type patternDef struct {
+	minLevel int
+	chords   []string
+}
+
+var patternDefs = []patternDef{
+	// --- Level 1: pickup lines, no hazards ---
+	{1, []string{ // center run
+		"...|.*.|...",
+		"...|.*.|...",
+		"...|.*.|...",
+	}},
+	{1, []string{ // left lane run
+		"...|*..|...",
+		"...|*..|...",
+		"...|*..|...",
+	}},
+	{1, []string{ // right lane run
+		"...|..*|...",
+		"...|..*|...",
+		"...|..*|...",
+	}},
+	{1, []string{ // jump arc
+		"...|.*.|...",
+		".*.|...|...",
+		".*.|...|...",
+		"...|.*.|...",
+	}},
+	{1, []string{ // slide dip
+		"...|.*.|...",
+		"...|...|.*.",
+		"...|...|.*.",
+		"...|.*.|...",
+	}},
+	{1, []string{ // lane sweep L→R
+		"...|*..|...",
+		"...|.*.|...",
+		"...|..*|...",
+	}},
+
+	// --- Level 2: single telegraphed obstacles ---
+	{2, []string{ // hop wall: energy above hazard
+		"...|.*.|...",
+		".*.|.#.|...",
+		"...|.*.|...",
+	}},
+	{2, []string{ // duck wall: energy below hazard
+		"...|.*.|...",
+		"...|.#.|.*.",
+		"...|.*.|...",
+	}},
+	{2, []string{ // side pinch: hold center
+		"...|.*.|...",
+		"...|#.#|...",
+		"...|#.#|...",
+		"...|.*.|...",
+	}},
+	{2, []string{ // forced left lane
+		"...|*..|...",
+		"...|*.#|...",
+		"...|*.#|...",
+		"...|.*.|...",
+	}},
+	{2, []string{ // magnet lure
+		"...|.*.|...",
+		"...|.M.|...",
+		"*.*|...|*.*",
+		"...|.*.|...",
+	}},
+	{2, []string{ // shield cache: armor, then the wall that spends it
+		"...|.*.|...",
+		"...|.S.|...",
+		"...|.#.|...",
+		"...|.*.|...",
+	}},
+	{2, []string{ // boost dash — tempo alone, no hazards
+		"...|.B.|...",
+		"...|.*.|...",
+		"...|*..|...",
+		"...|..*|...",
+		"...|*..|...",
+		"...|.*.|...",
+	}},
+
+	// --- Level 3+: combinations ---
+	{3, []string{ // hop then duck
+		"...|.*.|...",
+		".*.|.#.|...",
+		"...|.*.|...",
+		"...|.#.|.*.",
+		"...|.*.|...",
+	}},
+	{3, []string{ // tunnel: mid row only (Down cancels a stray jump in time)
+		"...|.*.|...",
+		"###|.S.|###",
+		"###|.*.|###",
+		"###|.*.|###",
+		"...|.*.|...",
+	}},
+	{3, []string{ // top weave R→L over walls (single jump spans it at base PDZ)
+		"...|.*.|...",
+		"..*|.##|...",
+		".*.|#.#|...",
+		"*..|##.|...",
+		"...|.*.|...",
+	}},
+	{3, []string{ // pillar dodge: center blocked, side lanes rewarded
+		"...|.*.|...",
+		".#.|*#*|.#.",
+		"...|.*.|...",
+	}},
+	{3, []string{ // trap lane: center reopens for a single chord, then shuts again. Exercises the TimerTrapSuffix marker
+		"...|.*.|...",
+		"...|.#.|...",
+		"...|.#.|...",
+		".*.|...|...",
+		"...|.#.|...",
+		"...|.#.|...",
+		"...|.*.|...",
+	}},
+	{3, []string{ // boost run: hazard-free corridor — the double tempo turns the lane hops into the skill test
+		"...|.B.|...",
+		"...|.*.|...",
+		"...|*.*|...",
+		"...|.*.|...",
+		"...|*.*|...",
+		"...|.*.|...",
+	}},
+	{3, []string{ // boost gauntlet — mid-center is open at every chord
+		"...|.B.|...",
+		"...|.*.|...",
+		"#.#|.*.|#.#",
+		"*.*|.*.|*.*",
+		"#.#|.*.|#.#",
+		"...|.*.|...",
+	}},
+
+	{4, []string{ // armored gauntlet: a walking wall run. Weave the mid row or jump it; the shield covers one mistimed lane change
+		"...|.S.|...",
+		"...|.*.|...",
+		"...|##.|...",
+		"...|.##|...",
+		"...|#.#|...",
+		"...|.*.|...",
+	}},
+}
+
+// pattern is the parsed, playable form
+type pattern struct {
+	minLevel int
+	chords   []types.Chord
+}
+
+var patterns []pattern
+
+func init() {
+	patterns = make([]pattern, len(patternDefs))
+	for i, d := range patternDefs {
+		p := pattern{minLevel: d.minLevel, chords: make([]types.Chord, len(d.chords))}
+		for j, s := range d.chords {
+			p.chords[j] = parseChord(s)
+		}
+		patterns[i] = p
+	}
+}
+
+// parseChord decodes a "TTT|MMM|BBB" literal; panics on malformed input or on
+// a kind the engine cannot resolve (author error, caught at process start).
+// Byte indexing is sound: types asserts every glyph is ASCII
+func parseChord(s string) types.Chord {
+	rows := strings.Split(s, "|")
+	if len(rows) != parameter.GamePlayIndexYMax {
+		panic(fmt.Sprintf("pattern chord %q: want %d rows", s, parameter.GamePlayIndexYMax))
+	}
+	var c types.Chord
+	for y, row := range rows {
+		if len(row) != parameter.GamePlayIndexXMax {
+			panic(fmt.Sprintf("pattern row %q: want %d cells", row, parameter.GamePlayIndexXMax))
+		}
+		for x, r := range row {
+			v, ok := types.ValueByGlyph(r)
+			if !ok {
+				panic(fmt.Sprintf("pattern cell %q: unknown glyph", string(r)))
+			}
+			if v != types.ValueNone && resolvers[v] == nil {
+				panic(fmt.Sprintf("pattern cell %q: %s has no engine resolver", string(r), v))
+			}
+			c.Notes[y][x] = types.Note{Value: v}
+		}
+	}
+	return c
+}
+
+// newSong builds a level: intro rest, pattern chains separated by rest gaps
+// that shrink with level, outro rest. The pool widens as level unlocks higher
+// minLevel entries; chains lengthen with level
+func newSong(level int) *types.Song {
+	length := min(
+		parameter.SongBaseLength+(level-1)*parameter.SongLengthPerLevel,
+		parameter.GamePlayIndexZMax,
+	)
+
+	pool := make([]pattern, 0, len(patterns))
+	for _, p := range patterns {
+		if p.minLevel <= level {
+			pool = append(pool, p)
+		}
+	}
+
+	chords := make([]types.Chord, 0, length)
+	chords = append(chords, make([]types.Chord, parameter.GenIntroRest)...)
+
+	budget := length - parameter.GenOutroRest
+	rest := max(parameter.GenRestBase-(level-1), parameter.GenRestMin)
+
+build:
+	for {
+		chain := parameter.GenChainBase +
+			rand.IntN(min(level, parameter.GenChainMax-parameter.GenChainBase)+1)
+		for range chain {
+			p := pool[rand.IntN(len(pool))]
+			if len(chords)+len(p.chords) > budget {
+				break build
+			}
+			// Value-copy append: runtime consumption mutates the Song,
+			// never the templates
+			chords = append(chords, p.chords...)
+			if rand.Float64() < parameter.GenBreatherProbability && len(chords) < budget {
+				chords = append(chords, types.Chord{})
+			}
+		}
+		if len(chords)+rest > budget {
+			break
+		}
+		chords = append(chords, make([]types.Chord, rest)...)
+	}
+
+	// Pad to exact length; tail padding doubles as outro rest
+	for len(chords) < length {
+		chords = append(chords, types.Chord{})
+	}
+
+	return &types.Song{Chords: chords}
+}
@@ -0,0 +1,65 @@
+package game
+
+import (
+	"symph/parameter"
+	"time"
+)
+
+// Status is the persistent player effect state granted by items. It survives a
+// level change and is cleared on restart. Timed effects hold an absolute
+// deadline, charge effects a count. Adding an effect adds a field here plus a
+// row in resolvers — the pause/interlude shift and the restart clear are
+// already funneled through this type
+type Status struct {
+	BoostUntil time.Time // zero or past = inactive
+	Shield     int       // charges; each absorbs one negative contact. No expiry
+}
+
+// Shielded reports whether an absorb charge is held
+func (s Status) Shielded() bool { return s.Shield > 0 }
+
+// Boosted reports whether a Boost is active at instant t. Drives the tempo
+// (deltaAt, evaluated at beat boundaries) and hazard immunity (hitHazard,
+// evaluated at the contact instant)
+func (s Status) Boosted(t time.Time) bool {
+	return !s.BoostUntil.IsZero() && t.Before(s.BoostUntil)
+}
+
+// BoostRemaining reports the Boost span left at t; 0 when inactive
+func (s Status) BoostRemaining(t time.Time) time.Duration {
+	if !s.Boosted(t) {
+		return 0
+	}
+	return s.BoostUntil.Sub(t)
+}
+
+// shift moves every absolute deadline forward by d, holding the remaining span
+// across a pause or a level-clear interlude
+// `at` is the instant the dead span opened. A deadline already lapsed
+// at `at` is cleared, not shifted — dead time never revives an effect
+func (s *Status) shift(at time.Time, d time.Duration) {
+	if s.BoostUntil.IsZero() {
+		return
+	}
+	if !s.Boosted(at) {
+		s.BoostUntil = time.Time{}
+		return
+	}
+	s.BoostUntil = s.BoostUntil.Add(d)
+}
+
+// grantShield arms the absorb charge. Charges do not stack: a pickup while
+// shielded re-arms
+func (s *Status) grantShield() { s.Shield = parameter.ShieldCharges }
+
+// grantBoost re-arms the tempo deadline
+func (s *Status) grantBoost(now time.Time) { s.BoostUntil = now.Add(parameter.BoostDuration) }
+
+// absorb spends one charge; reports whether one was held
+func (s *Status) absorb() bool {
+	if s.Shield <= 0 {
+		return false
+	}
+	s.Shield--
+	return true
+}
@@ -0,0 +1,17 @@
+module symph
+
+go 1.26.4
+
+require (
+	github.com/gen2brain/raylib-go/raylib v0.60.0
+	github.com/lixenwraith/color v0.0.0-20260714170240-79433f872c42
+	github.com/lixenwraith/terminal v0.0.0-20260714170427-21041633b2c3
+)
+
+require (
+	github.com/ebitengine/purego v0.10.1 // indirect
+	github.com/jupiterrider/ffi v0.7.0 // indirect
+	golang.org/x/exp v0.0.0-20260709172345-9ea1abe57597 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/term v0.45.0 // indirect
+)
@@ -0,0 +1,16 @@
+github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY=
+github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/gen2brain/raylib-go/raylib v0.60.0 h1:KsP7W3EMkmb9zztivdgbh1bXR78pEuqP6jeUR8GCbEA=
+github.com/gen2brain/raylib-go/raylib v0.60.0/go.mod h1:puAMU7Zcx6VJ6pcZSSs3gGFPyFvJuTwQlfm4KzeoXy8=
+github.com/jupiterrider/ffi v0.7.0 h1:RKsl6Ascal+3kyAqR5Qcbp83LceQMLc1VZbPfHWoNzs=
+github.com/jupiterrider/ffi v0.7.0/go.mod h1:9dauhpOfNqrqk28fxuu0kkdeFtT9Qr4vbfigiuIXN7c=
+github.com/lixenwraith/color v0.0.0-20260714170240-79433f872c42 h1:wBqu4zX4jtEOhQVTI1x492N/DKrNpawY4RSxGyDlEXM=
+github.com/lixenwraith/color v0.0.0-20260714170240-79433f872c42/go.mod h1:p02MsAGqlmZu3sc6BPYCKmaedF+lqBoijnuu5cOrYeo=
+github.com/lixenwraith/terminal v0.0.0-20260714170427-21041633b2c3 h1:9zbFMAZMb8V4Q4N3pHO/I9oSGwB6RNKC/p+rDPjNPeE=
+github.com/lixenwraith/terminal v0.0.0-20260714170427-21041633b2c3/go.mod h1:KSA1VFStFKduxZDbHlcA3ttdbMQf4dCd/9X36S/fS20=
+golang.org/x/exp v0.0.0-20260709172345-9ea1abe57597 h1:qLvzZeaANDgyVOA8pyHCOStGlXn0rseXma+GQjeuv2g=
+golang.org/x/exp v0.0.0-20260709172345-9ea1abe57597/go.mod h1:EdfpwwqSu+0Li0mzskwHU6FWDV3t9Q+RZDo3QMUtL3Q=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
@@ -0,0 +1,22 @@
+package input
+
+// Key is a platform-neutral physical key identifier. Terminal and raylib
+// frontends translate native key events to Key before consulting KeyMap.
+// Android/gomobile bypasses this package: Kotlin translates touch/gesture
+// input to game.Action directly
+type Key uint8
+
+const (
+	KeyNone      Key = iota
+	KeyH             // MoveLeft
+	KeyJ             // MoveDown
+	KeyK             // MoveUp
+	KeyL             // MoveRight
+	KeySemicolon     // stub
+	KeyA             // stub
+	KeyS             // stub
+	KeyD             // stub
+	KeyF             // stub
+	KeySpace
+	KeyEnter
+)
@@ -0,0 +1,26 @@
+package input
+
+import "symph/game"
+
+// KeyMap is the default vim-style binding
+var KeyMap = map[Key]game.Action{
+	KeyH:         game.ActionMoveLeft,
+	KeyJ:         game.ActionMoveDown,
+	KeyK:         game.ActionMoveUp,
+	KeyL:         game.ActionMoveRight,
+	KeySemicolon: game.ActionStubSemicolon,
+	KeyA:         game.ActionStubA,
+	KeyS:         game.ActionStubS,
+	KeyD:         game.ActionStubD,
+	KeyF:         game.ActionStubF,
+	KeySpace:     game.ActionSpace,
+	KeyEnter:     game.ActionConfirm,
+}
+
+// Translate resolves a Key to its bound Action, ActionNone if unbound
+func Translate(k Key) game.Action {
+	if a, ok := KeyMap[k]; ok {
+		return a
+	}
+	return game.ActionNone
+}
@@ -0,0 +1,116 @@
+package parameter
+
+// Row-reset funnels, drawn in the inter-tile gap row of the player lane.
+// Drop = jump expiry (falling to the base row), Rise = slide expiry.
+// %s is the countdown; formatted width must not exceed RenderNoteWidth
+const (
+	DropFunnelFormat = `\\ %s //`
+	RiseFunnelFormat = `// %s \\`
+)
+
+// Inbound — chords until the lane shuts.
+// Clear — chords until the lane reopens.
+// Open — the wall run reaches the window edge; the value is a lower bound.
+// Trap — the lane reopens for <= TrapGapMax chords before shutting again;
+// flagged on both the inbound and the clear timer
+const (
+	TimerInboundPrefix = '▼'
+	TimerClearPrefix   = '▲'
+	TimerOpenSuffix    = '+'
+	TimerTrapSuffix    = '!'
+)
+
+// StripEmptyChar is lookahead strip rail cell — a chord with no content at this position
+const StripEmptyChar = '·'
+
+// ItemFadeChars is the glyph tail of a consumed item's burn-out. Stage 0
+// keeps the item glyph; later stages collapse it into the rail cell
+var ItemFadeChars = [...]rune{'+', StripEmptyChar}
+
+// UnknownChar is placeholder for a Value with no authored visual.
+// Keeps NoteVisual total so an unrendered kind is visible rather than eating an item slot
+const UnknownChar = '?'
+
+// MutedText marks the host audio gate in the header. ASCII, so it
+// renders in both atlases
+const MutedText = "MUTE"
+
+// QuadrantChars provides 2x2 sub-cell resolution for TrueColor mode
+// Bitmap encoding: bit0=UL, bit1=UR, bit2=LL, bit3=LR
+// Layout: [UL][UR]
+//
+//	[LL][LR]
+var QuadrantChars = [16]rune{
+	' ', // 0000 - empty
+	'▘', // 0001 - upper-left
+	'▝', // 0010 - upper-right
+	'▀', // 0011 - upper half
+	'▖', // 0100 - lower-left
+	'▌', // 0101 - left half
+	'▞', // 0110 - anti-diagonal
+	'▛', // 0111 - UL + UR + LL
+	'▗', // 1000 - lower-right
+	'▚', // 1001 - diagonal
+	'▐', // 1010 - right half
+	'▜', // 1011 - UL + UR + LR
+	'▄', // 1100 - lower half
+	'▙', // 1101 - UL + LL + LR
+	'▟', // 1110 - UR + LL + LR
+	'█', // 1111 - full block
+}
+
+// Half256Chars provides vertical half-cell resolution for 256-color mode.
+// Unicode block characters, CP437-equivalent visuals, naked-TTY compatible
+// Bitmap encoding: bit0=top, bit1=bottom
+var Half256Chars = [4]rune{
+	' ',      // 00 - empty
+	'\u2580', // 01 - top half only (▀)
+	'\u2584', // 10 - bottom half only (▄)
+	'\u2588', // 11 - both halves (█)
+}
+
+// Horizontal256Chars provides horizontal half-cell characters.
+// Reserved for future horizontal sub-pixel support
+var Horizontal256Chars = [2]rune{
+	'\u258C', // ▌ - left half
+	'\u258E', // ▐ - right half
+}
+
+// Density256Chars provides intensity variants for trail and glow effects,
+// ordered lowest to highest density. Also indexes wall proximity bands
+var Density256Chars = [4]rune{
+	'\u2591', // ░ - light shade (25%)
+	'\u2592', // ▒ - medium shade (50%)
+	'\u2593', // ▓ - dark shade (75%)
+	'\u2588', // █ - full block (100%)
+}
+
+// Single-line box drawing characters
+const (
+	BorderSingleHorizontal     = '─' // U+2500
+	BorderSingleVertical       = '│' // U+2502
+	BorderSingleTopLeft        = '┌' // U+250C
+	BorderSingleTopRight       = '┐' // U+2510
+	BorderSingleBottomLeft     = '└' // U+2514
+	BorderSingleBottomRight    = '┘' // U+2518
+	BorderSingleVerticalRight  = '├' // U+251C
+	BorderSingleVerticalLeft   = '┤' // U+2524
+	BorderSingleHorizontalDown = '┬' // U+252C
+	BorderSingleHorizontalUp   = '┴' // U+2534
+	BorderSingleCross          = '┼' // U+253C
+)
+
+// Double-line box drawing characters
+const (
+	BorderDoubleHorizontal     = '═' // U+2550
+	BorderDoubleVertical       = '║' // U+2551
+	BorderDoubleTopLeft        = '╔' // U+2554
+	BorderDoubleTopRight       = '╗' // U+2557
+	BorderDoubleBottomLeft     = '╚' // U+255A
+	BorderDoubleBottomRight    = '╝' // U+255D
+	BorderDoubleVerticalRight  = '╠' // U+2560
+	BorderDoubleVerticalLeft   = '╣' // U+2563
+	BorderDoubleHorizontalDown = '╦' // U+2566
+	BorderDoubleHorizontalUp   = '╩' // U+2569
+	BorderDoubleCross          = '╬' // U+256C
+)
@@ -0,0 +1,159 @@
+package parameter
+
+import (
+	"time"
+)
+
+// Core game grid and timing
+const (
+	// GameRenderUpdate is the frontend frame interval (~60fps). Beat
+	// quantization is owned by the engine; this only paces UI wakeups
+	GameRenderUpdate = 16 * time.Millisecond
+
+	// GameDeltaZBase is the level-1 inter-chord interval. GameDeltaZStep
+	// shortens it per level down to the GameDeltaZMin floor
+	GameDeltaZBase = 500 * time.Millisecond
+	GameDeltaZStep = 20 * time.Millisecond
+	GameDeltaZMin  = 300 * time.Millisecond
+
+	// PlayerRowResetChords chords at whatever tempo is running, so a pattern's
+	// landing chord is invariant across levels and across a Boost.
+	// 3 * GameDeltaZBase == the previous 1500ms; level 1 is unchanged.
+	// Lane (X) shifts are persistent and never auto-reset
+	PlayerRowResetChords = 3
+
+	// ItemFadeDuration is the burn-out span of a consumed positive item.
+	// Kept under GameDeltaZMin/BoostSpeedFactor so the effect always completes inside one
+	// chord and reads as consumption, not as the strip scrolling
+	ItemFadeDuration = 140 * time.Millisecond
+
+	// ItemFlashFraction is the leading white-flash portion of the burn-out
+	ItemFlashFraction = 0.25
+
+	// TransitionDuration is the level-clear interlude length
+	TransitionDuration = 2000 * time.Millisecond
+
+	// Song length ceiling
+	GamePlayIndexZMax = 256
+
+	// Chord dimensions
+	GamePlayIndexYMax = 3
+	GamePlayIndexXMax = 3
+
+	// Player spawn position (grid center)
+	GamePlayIndexYStart = GamePlayIndexYMax / 2
+	GamePlayIndexXStart = GamePlayIndexXMax / 2
+)
+
+// Song generation
+const (
+	// SongBaseLength + (level-1)*SongLengthPerLevel chords per level,
+	// capped at GamePlayIndexZMax
+	SongBaseLength     = 72
+	SongLengthPerLevel = 12
+
+	// Guaranteed empty chords at song edges (grace-in, clean finish)
+	GenIntroRest = 6
+	GenOutroRest = 4
+
+	// Rest gap between pattern chains: GenRestBase shrinks by one per level
+	// down to GenRestMin
+	GenRestBase = 7
+	GenRestMin  = 2
+
+	// Patterns chained back-to-back per burst
+	GenChainBase = 1
+	GenChainMax  = 5
+
+	// Chance of a single empty chord between chained patterns
+	GenBreatherProbability = 0.5
+)
+
+// Lookahead observation window. Window width covers every wall band; band
+// geometry and trap threshold are parameterized here
+const (
+	// PositionLookaheadWindow is how many upcoming chords (starting at the
+	// current one, distance 0) are scanned per grid position.
+	// Hard ceiling: game.TileLookaheadMaxWindow (wall bitmask width)
+	PositionLookaheadWindow = 10
+
+	// Wall proximity bands. Band 0 is the arrived wall (distance 0); bands
+	// 1..WallBandCount-1 each span WallBandSize chords. Band index selects
+	// border fill density and color
+	WallBandSize  = 3
+	WallBandCount = 4
+
+	// TrapGapMax is the largest reopen gap still flagged as a trap: a lane
+	// that clears for <= this many chords before another wall shuts it
+	TrapGapMax = 2
+
+	// ConsumeRingSize bounds the consumed-note ring the frontends read
+	// for burn-out. A magnet sweep can consume up to
+	// GamePlayIndexYMax*GamePlayIndexXMax*PositionLookaheadWindow notes; on
+	// overflow the oldest burn-out is dropped (visual-only degradation)
+	ConsumeRingSize = 64
+
+	// MorphWindow is the chord-distance over which a non-wall Value's color
+	// interpolates from distant to arrived
+	MorphWindow = 4
+)
+
+// Player effects granted by items. Both survive a level change and are cleared on restart
+const (
+	// BoostDuration is the wall-clock lifetime of a Boost. A second pickup
+	// refreshes the deadline, it does not extend it
+	BoostDuration = 10 * time.Second
+
+	// BoostSpeedFactor divides the inter-chord interval while a Boost runs.
+	// Integer divisor: the boosted interval stays exact. A slow effect would
+	// multiply in the same place
+	BoostSpeedFactor = 2
+
+	// BoostWarnRemaining is the Boost tail over which the HUD countdown blinks.
+	// Expiry inside a wall band kills on the next beat; the player
+	// needs the lead time to leave the lane
+	BoostWarnRemaining = 2 * time.Second
+
+	// ShieldCharges is the charge count a Shield pickup arms. Each charge
+	// absorbs one negative contact; charges never expire and do not stack
+	ShieldCharges = 1
+)
+
+// The burn-out must finish inside the tightest beat — the level floor divided by the Boost factor.
+// Also proves the boosted interval is > 0, which bounds the Update beat loop
+const _ = uint(GameDeltaZMin/BoostSpeedFactor - ItemFadeDuration)
+
+// Compile-time: the window must reach the far edge of the last band
+const _ = uint(PositionLookaheadWindow - (WallBandSize*(WallBandCount-1) + 1))
+
+// Tile geometry derives from the strip. PositionLookaheadWindow is
+// the only knob; width follows so the strip is 1:1 with the interior
+const (
+	RenderMarginX = 1
+	RenderMarginY = 1
+
+	// RenderHeaderRows is the chrome above the grid (LEVEL / ENERGY).
+	// No footer, no title
+	RenderHeaderRows = 1
+
+	// One interior column per lookahead chord, plus the two border columns
+	RenderNoteWidth  = PositionLookaheadWindow + 2
+	RenderNoteHeight = 5
+
+	RenderGapX = 2
+	RenderGapY = 1
+
+	// Fixed interior row offsets, relative to the tile top border
+	RenderRowTimer = 1
+	RenderRowDist  = 2
+	RenderRowStrip = 3
+
+	// Distance row: "gDD gDD" — glyph + chord-distance, positive group then negative group
+	RenderDistDigits = 2
+	RenderDistCols   = 2*(1+RenderDistDigits) + 1
+
+	// RenderBlinkPeriod is the half-cycle of the nearest-item blink. The
+	// distance-row group of the tile(s) holding the grid-wide nearest
+	// positive/negative occurrence alternates between two colors at this rate
+	RenderBlinkPeriod = 120 * time.Millisecond
+)
@@ -0,0 +1,42 @@
+package render
+
+import (
+	"fmt"
+	"symph/parameter"
+)
+
+type noteTile = [parameter.RenderNoteHeight][parameter.RenderNoteWidth]rune
+
+var noteChar noteTile
+
+func init() {
+	funnel := max(
+		len(fmt.Sprintf(parameter.DropFunnelFormat, "0.0")),
+		len(fmt.Sprintf(parameter.RiseFunnelFormat, "0.0")),
+	)
+	inner := parameter.RenderNoteWidth - 2
+
+	// inner == PositionLookaheadWindow by construction; assert the
+	// distance row and funnel still fit
+	if parameter.RenderNoteHeight < 2+parameter.RenderRowStrip ||
+		inner < parameter.RenderDistCols ||
+		parameter.RenderNoteWidth < funnel ||
+		parameter.RenderGapY < 1 {
+		panic("Render tile too small: need height>=5, width-2>=RenderDistCols, width>=funnel, gapY>=1")
+	}
+
+	noteChar[0][0] = parameter.BorderSingleTopLeft
+	noteChar[parameter.RenderNoteHeight-1][0] = parameter.BorderSingleBottomLeft
+	noteChar[0][parameter.RenderNoteWidth-1] = parameter.BorderSingleTopRight
+	noteChar[parameter.RenderNoteHeight-1][parameter.RenderNoteWidth-1] = parameter.BorderSingleBottomRight
+
+	for i := 1; i < parameter.RenderNoteWidth-1; i++ {
+		noteChar[0][i] = parameter.BorderSingleHorizontal
+		noteChar[parameter.RenderNoteHeight-1][i] = parameter.BorderSingleHorizontal
+	}
+
+	for i := 1; i < parameter.RenderNoteHeight-1; i++ {
+		noteChar[i][0] = parameter.BorderSingleVertical
+		noteChar[i][parameter.RenderNoteWidth-1] = parameter.BorderSingleVertical
+	}
+}
@@ -0,0 +1,47 @@
+package render
+
+import (
+	"time"
+
+	"symph/game"
+	"symph/parameter"
+	"symph/types"
+)
+
+// FadeGrid projects the engine's consumed-note ring onto strip coordinates for
+// one frame: burn-out progress per (y, x, chord-distance). Entries outside the
+// window or past ItemFadeDuration are dropped. A consumed cell at distance 0
+// scrolls off on the next beat; the fade is shorter than the tightest beat, so
+// it always resolves before the strip shifts
+type FadeGrid struct {
+	value [parameter.GamePlayIndexYMax][parameter.GamePlayIndexXMax][game.TileLookaheadMaxWindow]types.Value
+	t     [parameter.GamePlayIndexYMax][parameter.GamePlayIndexXMax][game.TileLookaheadMaxWindow]float64
+}
+
+func (f *FadeGrid) Refresh(s *game.GameState, now time.Time) {
+	*f = FadeGrid{}
+	for _, c := range s.Consumed() {
+		if c.Value == types.ValueNone {
+			continue
+		}
+		age := now.Sub(c.At)
+		if age < 0 || age >= parameter.ItemFadeDuration {
+			continue
+		}
+		d := c.Z - s.CurrentPlayIndexZ
+		if d < 0 || d >= game.TileLookaheadMaxWindow {
+			continue
+		}
+		f.value[c.Y][c.X][d] = c.Value
+		f.t[c.Y][c.X][d] = float64(age) / float64(parameter.ItemFadeDuration)
+	}
+}
+
+// At reports the item burning out at a strip cell and its progress in [0,1)
+func (f *FadeGrid) At(y, x, d int) (types.Value, float64, bool) {
+	if d < 0 || d >= game.TileLookaheadMaxWindow {
+		return types.ValueNone, 0, false
+	}
+	v := f.value[y][x][d]
+	return v, f.t[y][x][d], v != types.ValueNone
+}
@@ -0,0 +1,320 @@
+//go:build linux
+
+// Package raylib is the graphical frontend. Presentation parity with the
+// terminal renderer: wall-band ring, wall timer, distance row with grid-wide
+// blink, lookahead strip, player fill, reset funnel, consumption burn-out.
+// Policy is sourced from package render; only the medium differs.
+//
+// The raylib default font atlas covers codepoints 32..126
+// Walls draw as rectangles, only the distance row needs the substitute rune.
+package raylib
+
+import (
+	"fmt"
+	"math"
+	"time"
+
+	rl "github.com/gen2brain/raylib-go/raylib"
+
+	"symph/game"
+	"symph/parameter"
+	"symph/render"
+	"symph/types"
+
+	"github.com/lixenwraith/color"
+)
+
+const (
+	gridFrac   = 0.92 // grid extent as a fraction of the usable area
+	tileAspect = 0.62 // tile height / width; mirrors the 12x5 terminal tile
+	gapFrac    = 0.03
+
+	// Independent gap fractions. The row gap hosts the reset funnel,
+	// so it scales with tile height, not with usable width
+	gapFracX = 0.04 // column gap / usable width
+	gapFracY = 0.22 // row gap / tile height
+
+	// Funnel countdown geometry
+	funnelFrac          = 0.85 // font size / row gap
+	funnelFontMin int32 = 22
+
+	ringPx     = 2.0
+	ringWallPx = 4.0
+	wallBodyA  = 70 // alpha of the arrived-wall body fill
+
+	rowTimerY = 0.16 // tile-relative content rows
+	rowDistY  = 0.42
+	rowStripY = 0.74
+
+	fontHUD    int32 = 20
+	fontBanner int32 = 40
+)
+
+// Renderer draws GameState with raylib primitives
+type Renderer struct {
+	state *game.GameState
+	grid  render.GridScan
+	fade  render.FadeGrid
+
+	Muted bool
+}
+
+func NewRenderer(s *game.GameState) *Renderer {
+	return &Renderer{state: s}
+}
+
+func toRl(c color.RGB) rl.Color { return rl.NewColor(c.R, c.G, c.B, 255) }
+
+// Draw renders one frame. Call between rl.BeginDrawing()/EndDrawing()
+func (r *Renderer) Draw(screenW, screenH int32, now time.Time) {
+	rl.ClearBackground(rl.Black)
+
+	hud := float32(screenH) * 0.07
+	lvl := fmt.Sprintf("LEVEL %d", r.state.Level)
+	if r.Muted {
+		lvl += "  " + parameter.MutedText
+	}
+	rl.DrawText(lvl, 12, 10, fontHUD, toRl(color.CoolSilver))
+	en := fmt.Sprintf("ENERGY %d", r.state.Energy)
+	rl.DrawText(en, screenW-rl.MeasureText(en, fontHUD)-12, 10, fontHUD, toRl(color.PaleGold))
+
+	if s := render.StatusText(r.state, now); s != "" {
+		drawCentered(s, float32(screenW)/2, 10, fontHUD, toRl(render.StatusColor(r.state, now)))
+	}
+
+	switch r.state.Phase {
+	case game.PhaseLevelClear:
+		r.drawLevelClear(screenW, screenH, now)
+	case game.PhaseGameOver:
+		r.drawField(screenW, screenH, hud, now)
+		r.drawGameOver(screenW, screenH)
+	default:
+		r.drawField(screenW, screenH, hud, now)
+	}
+}
+
+// tileGeom is the resolved per-frame grid layout
+type tileGeom struct{ ox, oy, tw, th, gx, gy float32 }
+
+func layout(w, h int32, hud float32) tileGeom {
+	nx := float32(parameter.GamePlayIndexXMax)
+	ny := float32(parameter.GamePlayIndexYMax)
+
+	availW := float32(w) * gridFrac
+	availH := (float32(h) - hud) * gridFrac
+
+	g := tileGeom{}
+	g.gx = availW * gapFracX
+
+	g.tw = (availW - (nx-1)*g.gx) / nx
+	g.th = g.tw * tileAspect
+	g.gy = g.th * gapFracY // Row gap derives from tile height
+
+	// Height-bound screens: refit from the vertical budget.
+	// gy is proportional to th, so solve for th directly
+	if ny*g.th+(ny-1)*g.gy > availH {
+		g.th = availH / (ny + (ny-1)*gapFracY)
+		g.tw = g.th / tileAspect
+		g.gy = g.th * gapFracY
+	}
+
+	gw := nx*g.tw + (nx-1)*g.gx
+	gh := ny*g.th + (ny-1)*g.gy
+	g.ox = (float32(w) - gw) / 2
+	g.oy = hud + (float32(h)-hud-gh)/2
+	return g
+}
+
+func (r *Renderer) drawField(w, h int32, hud float32, now time.Time) {
+	r.grid.Refresh(r.state)
+	r.fade.Refresh(r.state, now)
+
+	g := layout(w, h, hud)
+	live := r.state.Phase == game.PhasePlaying && !r.state.Paused
+
+	for y := range parameter.GamePlayIndexYMax {
+		for x := range parameter.GamePlayIndexXMax {
+			rect := rl.NewRectangle(
+				g.ox+float32(x)*(g.tw+g.gx),
+				g.oy+float32(y)*(g.th+g.gy),
+				g.tw, g.th)
+			r.drawTile(rect, y, x, live, now)
+		}
+	}
+	if live {
+		r.drawResetFunnel(g, now)
+	}
+}
+
+// drawTile renders one grid position. The player fill runs first: raylib paints
+// opaque, so the background cannot be applied after the glyphs
+func (r *Renderer) drawTile(rect rl.Rectangle, y, x int, live bool, now time.Time) {
+	tl := r.grid.Tiles[y][x]
+	seg := tl.NearestWall()
+
+	if y == r.state.PlayerState.PlayIndexY && x == r.state.PlayerState.PlayIndexX {
+		rl.DrawRectangleRec(rect, toRl(render.PlayerBgFor(r.state.Status, now)))
+	}
+
+	ring, thick := toRl(render.RingIdle), float32(ringPx)
+	switch {
+	case seg.Distance == 0:
+		// Lane lethal at the current chord: solid body, matches the terminal
+		// border fill
+		ring, thick = toRl(render.WallBandColor(0)), float32(ringWallPx)
+		body := ring
+		body.A = wallBodyA
+		rl.DrawRectangleRec(rect, body)
+	case seg.Distance > 0:
+		ring = toRl(render.WallBandColor(seg.Distance))
+	}
+	rl.DrawRectangleLinesEx(rect, thick, ring)
+
+	fs := fontSize(rect)
+	r.drawWallTimer(rect, fs, seg, live, now)
+	r.drawDistRow(rect, fs, tl, live, now)
+	r.drawStrip(rect, y, x, tl)
+}
+
+func fontSize(rect rl.Rectangle) int32 { return max(int32(rect.Height*0.19), 10) }
+
+func drawCentered(s string, cx, y float32, fs int32, c rl.Color) {
+	rl.DrawText(s, int32(cx)-rl.MeasureText(s, fs)/2, int32(y), fs, c)
+}
+
+func (r *Renderer) drawWallTimer(rect rl.Rectangle, fs int32, seg game.WallSegment, live bool, now time.Time) {
+	if !live {
+		return
+	}
+	s, c := render.WallTimerText(render.TimerASCII, r.state, seg, now)
+	if s == "" {
+		return
+	}
+	drawCentered(s, rect.X+rect.Width/2, rect.Y+rect.Height*rowTimerY, fs, toRl(c))
+}
+
+// drawDistRow draws two fixed polarity groups: nearest help, nearest threat.
+// A group whose distance equals the grid-wide nearest for its polarity blinks;
+// ties are not broken
+func (r *Renderer) drawDistRow(rect rl.Rectangle, fs int32, tl game.TileLookahead, live bool, now time.Time) {
+	if tl.Positive.Distance < 0 && tl.Negative.Distance < 0 {
+		return
+	}
+	cx, y := rect.X+rect.Width/2, rect.Y+rect.Height*rowDistY
+	off := rect.Width * 0.19
+
+	r.drawDistGroup(cx-off, y, fs, tl.Positive,
+		live && tl.Positive.Distance == r.grid.NearPos, render.BlinkPositive, now)
+	r.drawDistGroup(cx+off, y, fs, tl.Negative,
+		live && tl.Negative.Distance == r.grid.NearNeg, render.BlinkNegative, now)
+}
+
+func (r *Renderer) drawDistGroup(cx, y float32, fs int32, it game.ItemStat, blink bool, pair [2]color.RGB, now time.Time) {
+	if it.Distance < 0 {
+		return
+	}
+	ch, c := render.TileGlyphASCII(it.Value, it.Distance)
+	if blink {
+		c = render.BlinkColor(pair, now)
+	}
+	drawCentered(string(ch)+render.DistText(it.Distance), cx, y, fs, toRl(c))
+}
+
+// drawStrip renders the lane timeline: one cell per chord distance, leftmost =
+// the current chord. Items draw at arrived color (distance is positional),
+// walls keep the band gradient so ring, timer and strip agree. An emptied cell
+// with a pending burn-out flares and collapses in place
+func (r *Renderer) drawStrip(rect rl.Rectangle, y, x int, tl game.TileLookahead) {
+	pad := rect.Width * 0.06
+	cw := (rect.Width - 2*pad) / float32(parameter.PositionLookaheadWindow)
+	cy := rect.Y + rect.Height*rowStripY
+	rad := min(cw*0.42, rect.Height*0.10)
+
+	for d := range parameter.PositionLookaheadWindow {
+		cx := rect.X + pad + (float32(d)+0.5)*cw
+		if d >= tl.Window {
+			continue
+		}
+
+		switch v := tl.Cells[d]; {
+		case v == types.ValueWall:
+			_, c := render.TileGlyph(v, d)
+			rl.DrawRectangleRec(rl.NewRectangle(cx-cw*0.4, cy-rad, cw*0.8, rad*2), toRl(c))
+
+		case v != types.ValueNone:
+			_, c := render.TileGlyph(v, 0)
+			rl.DrawCircle(int32(cx), int32(cy), rad, toRl(c))
+
+		default:
+			fv, t, ok := r.fade.At(y, x, d)
+			if !ok {
+				rl.DrawCircle(int32(cx), int32(cy), rad*0.28, toRl(color.DimGray))
+				continue
+			}
+			c := toRl(render.FadeColor(fv, t))
+			c.A = uint8(255 * (1 - t)) // burn out to transparent
+			rl.DrawCircle(int32(cx), int32(cy), rad*float32(1.6-1.2*t), c)
+		}
+	}
+
+	// The chord being played
+	x0 := rect.X + pad
+	rl.DrawLineEx(
+		rl.NewVector2(x0, cy+rad*1.6), rl.NewVector2(x0+cw, cy+rad*1.6),
+		1.5, toRl(color.CoolSilver))
+}
+
+// drawResetFunnel renders the pending row-reset countdown in the gap adjacent
+// to the base-row tile of the player lane. Orientation follows the return
+// direction (fall after a jump, rise after a slide)
+func (r *Renderer) drawResetFunnel(g tileGeom, now time.Time) {
+	p := r.state.PlayerState
+	if p.ResetTime.IsZero() || p.PlayIndexY == p.BaseIndexY {
+		return
+	}
+
+	baseY := g.oy + float32(p.BaseIndexY)*(g.th+g.gy)
+	laneX := g.ox + float32(p.PlayIndexX)*(g.tw+g.gx)
+
+	arrow, gapY := "v", baseY-g.gy
+	if p.PlayIndexY > p.BaseIndexY {
+		arrow, gapY = "^", baseY+g.th
+	}
+
+	fs := max(int32(g.gy*funnelFrac), funnelFontMin)
+	s := fmt.Sprintf("%s %s %s", arrow, render.TimerText(p.ResetTime.Sub(now)), arrow)
+	drawCentered(s, laneX+g.tw/2, gapY+(g.gy-float32(fs))/2, fs, rl.White)
+}
+
+// --- Phase overlays ---
+
+// drawLevelClear renders expanding hue-cycled rings with the clear banner
+func (r *Renderer) drawLevelClear(w, h int32, now time.Time) {
+	el := now.Sub(r.state.PhaseStart).Seconds()
+	cx, cy := w/2, h/2
+	maxR := math.Hypot(float64(cx), float64(cy))
+
+	for i := range 24 {
+		rr := float32(math.Mod(el*220+float64(i)*44, maxR))
+		col := rl.ColorFromHSV(float32(math.Mod(el*120+float64(i)*15, 360)), 0.8, 1)
+		col.A = 200
+		rl.DrawCircleLines(cx, cy, rr, col)
+	}
+
+	msg := fmt.Sprintf("LEVEL %d CLEAR", r.state.Level)
+	rl.DrawText(msg, cx-rl.MeasureText(msg, fontBanner)/2, cy-fontBanner, fontBanner, rl.White)
+	sub := fmt.Sprintf("ENERGY %d", r.state.Energy)
+	rl.DrawText(sub, cx-rl.MeasureText(sub, fontHUD)/2, cy+12, fontHUD, rl.LightGray)
+}
+
+// drawGameOver overlays the death banner on the frozen field (the fatal wall
+// stays visible)
+func (r *Renderer) drawGameOver(w, h int32) {
+	rl.DrawRectangle(0, 0, w, h, rl.NewColor(0, 0, 0, 160))
+	msg := "GAME OVER"
+	rl.DrawText(msg, w/2-rl.MeasureText(msg, fontBanner)/2, h/2-fontBanner, fontBanner, toRl(color.BrightRed))
+	sub := fmt.Sprintf("ENERGY %d - LEVEL %d", r.state.Energy, r.state.Level)
+	rl.DrawText(sub, w/2-rl.MeasureText(sub, fontHUD)/2, h/2+8, fontHUD, toRl(color.Silver))
+	hint := "ENTER TO RESTART"
+	rl.DrawText(hint, w/2-rl.MeasureText(hint, fontHUD)/2, h/2+34, fontHUD, toRl(color.DimSilver))
+}
@@ -0,0 +1,458 @@
+// Package render draws GameState to a terminal cell buffer.
+//
+// Tile encoding (12x5):
+//   - border      — thin ring, colored by nearest-wall proximity band.
+//     Solid fill only when a wall occupies the current chord
+//   - interior r1 — wall timer, fixed position. ▼ = chords until the lane
+//     shuts, ▲ = chords until it reopens. '+' lower bound,
+//     '!' trap gap
+//   - interior r2 — distance row: nearest positive and nearest negative
+//     occurrence, each as glyph + chord-distance. The tile(s) holding the
+//     grid-wide nearest occurrence of a polarity blink that group
+//   - interior r3 — lookahead strip: one cell per chord, leftmost = now
+//   - background  — player position
+//
+// The header row carries LEVEL, the active-effect segment (shield charge, boost countdown), and ENERGY.
+//
+// The inter-tile gap row of the player lane hosts the row-reset funnel.
+package render
+
+import (
+	"fmt"
+	"math"
+	"time"
+	"unicode/utf8"
+
+	"symph/game"
+	"symph/parameter"
+	"symph/types"
+
+	"github.com/lixenwraith/color"
+	"github.com/lixenwraith/terminal"
+)
+
+type Renderer struct {
+	term          terminal.Terminal
+	state         *game.GameState
+	cells         []terminal.Cell
+	height, width int
+
+	Muted bool
+
+	// grid-scope scan and burn-out projection are shared helpers
+	grid GridScan
+	fade FadeGrid
+}
+
+func NewRenderer(t terminal.Terminal, w, h int, s *game.GameState) *Renderer {
+	r := &Renderer{term: t, state: s, height: h, width: w, cells: make([]terminal.Cell, w*h)}
+	r.clearFrame()
+	return r
+}
+
+func (r *Renderer) Resize(w, h int) {
+	r.height, r.width = h, w
+	r.cells = make([]terminal.Cell, w*h)
+	r.clearFrame()
+}
+
+// clearFrame blanks the logical buffer. Phase overlays paint outside tile
+// rectangles, so per-frame clearing prevents stale cells across phase
+// switches; the terminal Flush diffs, keeping the cost in-process
+func (r *Renderer) clearFrame() {
+	for i := range r.cells {
+		r.cells[i] = terminal.Cell{Rune: ' ', Bg: color.Black}
+	}
+}
+
+// MinSize is the frame size required to draw the full field. Below it
+// drawChar clips silently, so the frontend pauses and shows the notice
+func MinSize() (w, h int) {
+	gh, gw := gridSize()
+	return gw + 2*parameter.RenderMarginX,
+		gh + parameter.RenderHeaderRows + 2*parameter.RenderMarginY
+}
+
+func (r *Renderer) TooSmall() bool {
+	mw, mh := MinSize()
+	return r.width < mw || r.height < mh
+}
+
+func (r *Renderer) drawTooSmall() {
+	mw, mh := MinSize()
+	lines := [...]string{
+		"TERMINAL TOO SMALL",
+		fmt.Sprintf("need %dx%d", mw, mh),
+		fmt.Sprintf("have %dx%d", r.width, r.height),
+		"PAUSED - RESIZE TO RESUME",
+	}
+	top := max(0, (r.height-len(lines))/2)
+	for i, s := range lines {
+		fg := color.Silver
+		if i == 0 {
+			fg = color.BrightRed
+		}
+		drawText(r.cells, r.height, r.width, top+i,
+			max(0, (r.width-runeLen(s))/2), s, fg, terminal.AttrBold)
+	}
+}
+
+// Render draws one frame: chrome, then the phase-appropriate field
+func (r *Renderer) Render(now time.Time) {
+	// Ensure no terminal size desync
+	w, h := r.term.Size()
+	if w <= 0 || h <= 0 || w != r.width || h != r.height {
+		return
+	}
+
+	r.clearFrame()
+
+	if r.TooSmall() {
+		r.drawTooSmall()
+		r.term.Flush(r.cells, w, h)
+		return
+	}
+
+	topY, topX := r.gridOrigin()
+	_, gridW := gridSize()
+
+	hudL := fmt.Sprintf("LEVEL %d", r.state.Level)
+	if r.Muted {
+		hudL += "  " + parameter.MutedText
+	}
+	hudR := fmt.Sprintf("ENERGY %d", r.state.Energy)
+	drawText(r.cells, h, w, topY-1, topX, hudL, color.CoolSilver, terminal.AttrBold)
+	drawText(r.cells, h, w, topY-1, topX+gridW-runeLen(hudR), hudR, color.PaleGold, terminal.AttrBold)
+
+	// Active effects, centered between the HUD anchors
+	if s := StatusText(r.state, now); s != "" {
+		drawText(r.cells, h, w, topY-1, topX+(gridW-runeLen(s))/2, s,
+			StatusColor(r.state, now), terminal.AttrBold)
+	}
+
+	switch r.state.Phase {
+	case game.PhaseLevelClear:
+		r.drawLevelClear(topY, topX, now)
+	case game.PhaseGameOver:
+		r.drawChordGrid(topY, topX, now)
+		r.drawGameOver(topY)
+	default:
+		r.drawChordGrid(topY, topX, now)
+		r.drawResetFunnel(topY, topX, now)
+	}
+
+	r.term.Flush(r.cells, w, h)
+}
+
+// --- Geometry ---
+
+// gridSize returns the grid extent including inter-tile gaps
+func gridSize() (h, w int) {
+	h = parameter.GamePlayIndexYMax*parameter.RenderNoteHeight +
+		(parameter.GamePlayIndexYMax-1)*parameter.RenderGapY
+	w = parameter.GamePlayIndexXMax*parameter.RenderNoteWidth +
+		(parameter.GamePlayIndexXMax-1)*parameter.RenderGapX
+	return h, w
+}
+
+// gridOrigin computes the centered top-left cell for the chord grid, clamped below the header row
+func (r *Renderer) gridOrigin() (topY, topX int) {
+	gridH, gridW := gridSize()
+
+	topX = max(parameter.RenderMarginX, (r.width-gridW)/2)
+
+	topY = (r.height - gridH) / 2
+	topY = max(topY, parameter.RenderMarginY+parameter.RenderHeaderRows)
+	topY = min(topY, r.height-parameter.RenderMarginY-gridH)
+
+	return topY, topX
+}
+
+// tileOrigin resolves the top-left cell of grid tile (y,x)
+func tileOrigin(topY, topX, y, x int) (int, int) {
+	return topY + y*(parameter.RenderNoteHeight+parameter.RenderGapY),
+		topX + x*(parameter.RenderNoteWidth+parameter.RenderGapX)
+}
+
+// --- Playfield ---
+
+func (r *Renderer) drawChordGrid(topY, topX int, now time.Time) {
+	r.grid.Refresh(r.state)
+	r.fade.Refresh(r.state, now)
+	for iy := range parameter.GamePlayIndexYMax {
+		for ix := range parameter.GamePlayIndexXMax {
+			ty, tx := tileOrigin(topY, topX, iy, ix)
+			r.drawTile(ty, tx, iy, ix, now)
+		}
+	}
+}
+
+// drawTile renders one grid position: wall-encoded border, distance row, wall
+// timer, lookahead strip, and the player background fill. Background fill runs
+// last so it recolors without clobbering foreground glyphs
+func (r *Renderer) drawTile(topY, topX, y, x int, now time.Time) {
+	tl := r.grid.Tiles[y][x]
+	seg := tl.NearestWall()
+
+	switch {
+	case seg.Distance == 0:
+		r.drawWallRing(topY, topX, WallSolid, WallBandColor(0))
+	case seg.Distance > 0:
+		r.drawBoxRing(topY, topX, WallBandColor(seg.Distance))
+	default:
+		r.drawBoxRing(topY, topX, RingIdle)
+	}
+
+	// Timers and the blink are meaningless outside a running PhasePlaying:
+	// LastPlayedTime is frozen and the field does not advance
+	live := r.state.Phase == game.PhasePlaying && !r.state.Paused
+
+	r.drawWallTimer(topY+parameter.RenderRowTimer, topX, seg, live, now)
+	r.drawDistRow(topY+parameter.RenderRowDist, topX, tl, live, now)
+	r.drawStrip(topY+parameter.RenderRowStrip, topX, tl, y, x) // Fade lookup needs (y,x)
+
+	if y == r.state.PlayerState.PlayIndexY && x == r.state.PlayerState.PlayIndexX {
+		r.fillTileBg(topY, topX, PlayerBgFor(r.state.Status, now))
+	}
+}
+
+// drawWallTimer renders the fixed-position wall countdown.
+func (r *Renderer) drawWallTimer(row, topX int, seg game.WallSegment, live bool, now time.Time) {
+	if !live {
+		return
+	}
+	s, fg := WallTimerText(TimerUnicode, r.state, seg, now)
+	if s == "" {
+		return
+	}
+	r.drawTileText(row, topX, s, fg, terminal.AttrBold)
+}
+
+// drawStrip renders the lane timeline — one cell per chord distance, leftmost
+// = the current chord. Distance is carried positionally, so items render at
+// their arrived color and stay legible at range; walls keep the band gradient,
+// matching the ring. A cell emptied by consumption burns out in place
+func (r *Renderer) drawStrip(row, topX int, tl game.TileLookahead, y, x int) {
+	col := topX + 1 // inner == PositionLookaheadWindow
+
+	for d := range parameter.PositionLookaheadWindow {
+		ch, fg := parameter.StripEmptyChar, color.DimGray
+
+		if d < tl.Window {
+			switch v := tl.Cells[d]; {
+			case v == types.ValueWall:
+				ch, fg = TileGlyph(v, d)
+			case v != types.ValueNone:
+				ch, fg = TileGlyph(v, 0)
+			default:
+				// burn-out of a note the engine just consumed
+				if fv, t, ok := r.fade.At(y, x, d); ok {
+					ch, fg = FadeVisual(fv, t)
+				}
+			}
+		}
+
+		attr := terminal.AttrNone
+		if d == 0 {
+			attr = terminal.AttrBold // the chord being played
+		}
+		drawChar(r.cells, r.height, r.width, row, col+d, ch, fg, attr)
+	}
+}
+
+// drawWallRing fills the tile border with the wall proximity glyph. Adjacent
+// walled tiles merge into a contiguous mass
+func (r *Renderer) drawWallRing(topY, topX int, glyph rune, fg color.RGB) {
+	for ty := range parameter.RenderNoteHeight {
+		for tx := range parameter.RenderNoteWidth {
+			if ty > 0 && ty < parameter.RenderNoteHeight-1 &&
+				tx > 0 && tx < parameter.RenderNoteWidth-1 {
+				continue
+			}
+			drawChar(r.cells, r.height, r.width, topY+ty, topX+tx, glyph, fg, terminal.AttrNone)
+		}
+	}
+}
+
+// drawBoxRing draws the wall-free border from the tile template
+// ring color is a parameter — carries wall proximity when the wall
+// has not arrived
+func (r *Renderer) drawBoxRing(topY, topX int, fg color.RGB) {
+	for ty := range parameter.RenderNoteHeight {
+		for tx := range parameter.RenderNoteWidth {
+			if ch := noteChar[ty][tx]; ch != 0 {
+				drawChar(r.cells, r.height, r.width, topY+ty, topX+tx, ch, fg, terminal.AttrNone)
+			}
+		}
+	}
+}
+
+// drawDistRow draws two fixed polarity groups: nearest help, nearest threat,
+// each as glyph + chord-distance. 0 = at the current chord; an absent kind
+// draws nothing. A group whose distance equals the grid-wide nearest for its
+// polarity blinks — several tiles can tie and all of them blink
+func (r *Renderer) drawDistRow(row, topX int, tl game.TileLookahead, live bool, now time.Time) {
+	if tl.Positive.Distance < 0 && tl.Negative.Distance < 0 {
+		return
+	}
+
+	inner := parameter.RenderNoteWidth - 2
+	col := topX + 1 + (inner-parameter.RenderDistCols)/2
+
+	// grid-wide minima read from GridScan
+	r.drawDistGroup(row, col, tl.Positive,
+		live && tl.Positive.Distance == r.grid.NearPos, BlinkPositive, now)
+	r.drawDistGroup(row, col+parameter.RenderDistDigits+2, tl.Negative,
+		live && tl.Negative.Distance == r.grid.NearNeg, BlinkNegative, now)
+}
+
+func (r *Renderer) drawDistGroup(row, col int, it game.ItemStat, blink bool, pair [2]color.RGB, now time.Time) {
+	if it.Distance < 0 {
+		return
+	}
+	ch, fg := TileGlyph(it.Value, it.Distance)
+	if ch == 0 {
+		return
+	}
+	if blink {
+		fg = BlinkColor(pair, now)
+	}
+	drawChar(r.cells, r.height, r.width, row, col, ch, fg, terminal.AttrBold)
+	drawText(r.cells, r.height, r.width, row, col+1, DistText(it.Distance), fg, terminal.AttrBold)
+}
+
+// drawResetFunnel renders the pending row-reset countdown in the gap row
+// adjacent to the base-row tile of the player lane. Funnel orientation follows
+// the return direction (fall after a jump, rise after a slide)
+func (r *Renderer) drawResetFunnel(topY, topX int, now time.Time) {
+	p := r.state.PlayerState
+	if p.ResetTime.IsZero() || p.PlayIndexY == p.BaseIndexY {
+		return
+	}
+
+	baseY, laneX := tileOrigin(topY, topX, p.BaseIndexY, p.PlayIndexX)
+
+	format, row := parameter.DropFunnelFormat, baseY-parameter.RenderGapY
+	if p.PlayIndexY > p.BaseIndexY {
+		format, row = parameter.RiseFunnelFormat, baseY+parameter.RenderNoteHeight
+	}
+
+	s := fmt.Sprintf(format, TimerText(p.ResetTime.Sub(now)))
+	drawText(r.cells, r.height, r.width, row,
+		laneX+(parameter.RenderNoteWidth-len(s))/2, s, color.White, terminal.AttrBold)
+}
+
+// --- Phase overlays ---
+
+// transitionPalette cycles the level-clear wave hues
+var transitionPalette = [...]color.RGB{
+	color.Vermilion, color.TigerOrange, color.Gold,
+	color.BrightGreen, color.BrightCyan, color.Cornflower, color.HotMagenta,
+}
+
+// drawLevelClear paints a radial color wave expanding from the grid center
+// with the clear banner on top — retro inter-level interlude
+func (r *Renderer) drawLevelClear(topY, topX int, now time.Time) {
+	gridH, gridW := gridSize()
+
+	const padY, padX = 1, 3
+	cy := float64(topY) + float64(gridH-1)/2
+	cx := float64(topX) + float64(gridW-1)/2
+	el := now.Sub(r.state.PhaseStart).Seconds()
+	n := float64(len(transitionPalette))
+
+	for y := topY - padY; y < topY+gridH+padY; y++ {
+		for x := topX - padX; x < topX+gridW+padX; x++ {
+			dy := (float64(y) - cy) * 2.0 // terminal cell aspect ~1:2
+			dx := float64(x) - cx
+			ph := math.Hypot(dx, dy)*0.35 - el*8
+			pos := math.Mod(math.Mod(ph, n)+n, n) // positive wrap into palette cycle
+			i := int(pos)
+			frac := pos - float64(i)
+			col := transitionPalette[i].Lerp(transitionPalette[(i+1)%len(transitionPalette)], frac)
+			glyph := parameter.Density256Chars[int(frac*float64(len(parameter.Density256Chars)))]
+			drawChar(r.cells, r.height, r.width, y, x, glyph, col, terminal.AttrNone)
+		}
+	}
+
+	msg := fmt.Sprintf("  LEVEL %d CLEAR  ", r.state.Level)
+	sub := fmt.Sprintf("  ENERGY %d  ", r.state.Energy)
+	midY := topY + gridH/2
+	fg := color.White
+	if int(el*4)%2 == 0 {
+		fg = color.PaleLemon // blink
+	}
+	drawText(r.cells, r.height, r.width, midY-1, max(0, (r.width-len(msg))/2), msg, fg, terminal.AttrBold)
+	drawText(r.cells, r.height, r.width, midY+1, max(0, (r.width-len(sub))/2), sub, color.Silver, terminal.AttrBold)
+}
+
+// drawGameOver overlays the death banner on the frozen grid (fatal wall stays
+// visible)
+func (r *Renderer) drawGameOver(topY int) {
+	gridH, _ := gridSize()
+	midY := topY + gridH/2
+
+	msg := "  G A M E  O V E R  "
+	sub := fmt.Sprintf("  ENERGY %d - LEVEL %d  ", r.state.Energy, r.state.Level)
+	hint := "  ENTER TO RESTART  "
+
+	drawText(r.cells, r.height, r.width, midY-1, max(0, (r.width-len(msg))/2), msg, color.BrightRed, terminal.AttrBold)
+	drawText(r.cells, r.height, r.width, midY, max(0, (r.width-len(sub))/2), sub, color.Silver, terminal.AttrNone)
+	drawText(r.cells, r.height, r.width, midY+1, max(0, (r.width-len(hint))/2), hint, color.DimSilver, terminal.AttrNone)
+}
+
+// --- Cell primitives ---
+
+func runeLen(s string) int { return utf8.RuneCountInString(s) }
+
+// drawTileText centers s across the tile interior columns. Width is
+// rune-indexed; byte length misplaces the multi-byte timer affixes
+func (r *Renderer) drawTileText(row, topX int, s string, fg color.RGB, attr terminal.Attr) {
+	inner := parameter.RenderNoteWidth - 2
+	n := runeLen(s)
+	if n > inner {
+		return
+	}
+	drawText(r.cells, r.height, r.width, row, topX+1+(inner-n)/2, s, fg, attr)
+}
+
+// fillTileBg recolors the tile rectangle background in place. Runs after all
+// tile glyphs are written, so foreground content is preserved
+func (r *Renderer) fillTileBg(topY, topX int, bg color.RGB) {
+	for ty := range parameter.RenderNoteHeight {
+		y := topY + ty
+		if y < 0 || y >= r.height {
+			continue
+		}
+		for tx := range parameter.RenderNoteWidth {
+			x := topX + tx
+			if x < 0 || x >= r.width {
+				continue
+			}
+			r.cells[y*r.width+x].Bg = bg
+		}
+	}
+}
+
+// drawChar writes a single cell, bounds-checked
+func drawChar(cells []terminal.Cell, h, w, y, x int, char rune, fg color.RGB, attr terminal.Attr) {
+	if y < 0 || y >= h || x < 0 || x >= w {
+		return
+	}
+	cells[y*w+x] = terminal.Cell{Rune: char, Fg: fg, Bg: color.Black, Attrs: attr}
+}
+
+// drawText writes a horizontal string, rune-indexed (byte indexing misplaces
+// columns for non-ASCII text). Out-of-bounds columns are skipped
+func drawText(cells []terminal.Cell, h, w, y, x int, text string, fg color.RGB, attr terminal.Attr) {
+	if y < 0 || y >= h {
+		return
+	}
+	sx := x
+	for _, r := range text {
+		if sx >= 0 && sx < w {
+			cells[y*w+sx] = terminal.Cell{Rune: r, Fg: fg, Bg: color.Black, Attrs: attr}
+		}
+		sx++
+	}
+}
@@ -0,0 +1,32 @@
+package render
+
+import (
+	"symph/game"
+	"symph/parameter"
+)
+
+// GridScan caches one frame of per-position lookahead and resolves the
+// grid-wide nearest distances. Blink membership is a grid-scope property, so
+// every position is scanned before any tile is drawn. Allocation-free: fixed
+// arrays refilled in place, shared by both frontends
+type GridScan struct {
+	Tiles   [parameter.GamePlayIndexYMax][parameter.GamePlayIndexXMax]game.TileLookahead
+	NearPos int // grid-wide nearest positive distance; -1 when none
+	NearNeg int // grid-wide nearest negative distance; -1 when none
+}
+
+func (g *GridScan) Refresh(s *game.GameState) {
+	g.NearPos, g.NearNeg = -1, -1
+	for y := range parameter.GamePlayIndexYMax {
+		for x := range parameter.GamePlayIndexXMax {
+			tl := s.ScanTile(y, x, parameter.PositionLookaheadWindow)
+			g.Tiles[y][x] = tl
+			if d := tl.Positive.Distance; d >= 0 && (g.NearPos < 0 || d < g.NearPos) {
+				g.NearPos = d
+			}
+			if d := tl.Negative.Distance; d >= 0 && (g.NearNeg < 0 || d < g.NearNeg) {
+				g.NearNeg = d
+			}
+		}
+	}
+}
@@ -0,0 +1,281 @@
+package render
+
+import (
+	"fmt"
+	"symph/game"
+	"symph/parameter"
+	"symph/types"
+	"time"
+
+	"github.com/lixenwraith/color"
+)
+
+// Compile-time: one density glyph per wall band
+const _ = uint(len(parameter.Density256Chars) - parameter.WallBandCount)
+
+// PlayerBg is the tile-wide background of the player position — deep indigo,
+// contrasts against the black field while preserving legibility of every
+// foreground band color (yellow/orange/red) and item color
+var PlayerBg = color.RGB{R: 32, G: 40, B: 72}
+
+// A held shield charge and an active Boost are field state — immunity must read
+// at the point of contact, not only in the HUD. Both fills stay dark: every
+// wall band color and item color is high-luminance and must remain legible over
+// the player tile
+var (
+	PlayerShieldBg = color.RGB{R: 40, G: 72, B: 88}
+	PlayerBoostBg  = color.RGB{R: 64, G: 48, B: 16}
+)
+
+// PlayerBgFor selects the player fill for the active status. Boost outranks
+// Shield: it is the effect absorbing the contact
+func PlayerBgFor(s game.Status, now time.Time) color.RGB {
+	switch {
+	case s.Boosted(now):
+		return PlayerBoostBg
+	case s.Shielded():
+		return PlayerShieldBg
+	}
+	return PlayerBg
+}
+
+// RingIdle is the border color of a tile with no wall in the window
+var RingIdle = color.Teal
+
+// --- Wall proximity (terminal border encoding) ---
+
+// wallBandColor is indexed by proximity band (0 = arrived)
+var wallBandColor = [parameter.WallBandCount]color.RGB{
+	color.BrightRed,   // 0: arrived
+	color.Vermilion,   // 1: dark orange
+	color.TigerOrange, // 2: light orange
+	color.Yellow,      // 3: far
+}
+
+// WallSolid is the arrived-wall glyph (100% density)
+var WallSolid = parameter.Density256Chars[len(parameter.Density256Chars)-1]
+
+// WallBand maps a chord distance to a proximity band (0 = arrived).
+// Distances past the last band clamp to it
+func WallBand(distance int) int {
+	if distance <= 0 {
+		return 0
+	}
+	return min((distance+parameter.WallBandSize-1)/parameter.WallBandSize, parameter.WallBandCount-1)
+}
+
+// WallBandColor maps a chord distance to its proximity band color. Band 0
+// (arrived) is bright red; receding bands cool through orange to yellow.
+// Border fill is binary — a filled ring means the lane is lethal at the
+// current chord — so approach urgency rides on ring color alone
+func WallBandColor(distance int) color.RGB {
+	return wallBandColor[WallBand(distance)]
+}
+
+// --- Item / note visuals ---
+
+// valueVisual is the appearance of a Value in the strip and distance row: the
+// distant→arrived color ramp. Both endpoints are high-luminance so a distant
+// item stays visible against the black field. Item ramps avoid the wall band
+// family (red/orange/yellow); unauthored kinds fall back to the dim
+// unknownVisual rather than eating an item slot
+type valueVisual struct {
+	far, near color.RGB
+	authored  bool
+}
+
+var valueVisuals = [types.ValueCount]valueVisual{
+	types.ValueEnergy: {color.BrightCyan, color.BrightGreen, true},
+	types.ValueMagnet: {color.Cornflower, color.HotMagenta, true},
+	types.ValueShield: {color.CoolSilver, color.White, true},
+	types.ValueBoost:  {color.PaleLemon, color.Gold, true},
+}
+
+var unknownVisual = valueVisual{color.DimSilver, color.Silver, true}
+
+// TileGlyph resolves the strip and distance-row glyph for a Value at a given chord distance.
+// Walls follow the border band encoding so the ring, strip, and distance row agree.
+// Items use the morph lerp over their authored ramp
+func TileGlyph(v types.Value, distance int) (rune, color.RGB) {
+	if v == types.ValueWall {
+		return WallSolid, WallBandColor(distance)
+	}
+	if !v.Valid() || v == types.ValueNone {
+		return 0, color.RGB{}
+	}
+	t := proximity(distance)
+	if vis := valueVisuals[v]; vis.authored {
+		return v.Glyph(), vis.far.Lerp(vis.near, t)
+	}
+	return parameter.UnknownChar, unknownVisual.far.Lerp(unknownVisual.near, t)
+}
+
+// TileGlyphASCII resolves the glyph for a frontend limited to the 32..126 atlas:
+// the wall's density block is substituted with its authoring rune. Colors are
+// identical, so the two frontends stay in presentation parity
+func TileGlyphASCII(v types.Value, distance int) (rune, color.RGB) {
+	ch, c := TileGlyph(v, distance)
+	if v == types.ValueWall {
+		ch = v.Glyph()
+	}
+	return ch, c
+}
+
+// proximity maps a chord distance to [0,1]: 1 = arrived (distance<=0),
+// 0 = at or beyond MorphWindow chords away
+func proximity(distance int) float64 {
+	if distance <= 0 {
+		return 1
+	}
+	if distance >= parameter.MorphWindow {
+		return 0
+	}
+	return 1 - float64(distance)/float64(parameter.MorphWindow)
+}
+
+// --- HUD effect segment ---
+
+// StatusText composes the active-effect HUD segment: the Shield charge glyph
+// and the Boost countdown. Glyphs are the ASCII authoring runes, so the string
+// is renderable in both atlases. Empty outside a running PhasePlaying — the
+// deadlines are frozen there and a ticking countdown would be a lie
+func StatusText(s *game.GameState, now time.Time) string {
+	if s.Phase != game.PhasePlaying || s.Paused {
+		return ""
+	}
+	out := make([]rune, 0, 8)
+	if s.Status.Shielded() {
+		out = append(out, types.ValueShield.Glyph())
+	}
+	if s.Status.Boosted(now) {
+		if len(out) > 0 {
+			out = append(out, ' ')
+		}
+		out = append(out, types.ValueBoost.Glyph(), ' ')
+		out = append(out, []rune(TimerText(s.Status.BoostRemaining(now)))...)
+	}
+	return string(out)
+}
+
+// StatusColor tints the effect segment with the arrived color of the expiring
+// effect — the Boost when one runs, else the Shield
+func StatusColor(s *game.GameState, now time.Time) color.RGB {
+	if rem := s.Status.BoostRemaining(now); rem > 0 {
+		if rem <= parameter.BoostWarnRemaining {
+			return BlinkColor(BlinkNegative, now)
+		}
+		_, c := TileGlyph(types.ValueBoost, 0)
+		return c
+	}
+	_, c := TileGlyph(types.ValueShield, 0)
+	return c
+}
+
+// --- Consumption burn-out ---
+
+// FadeColor is the burn-out color of a consumed item at progress t in
+// [0,1): a white flash, then a sink into the field. Distinguishes consumption
+// from the cell scrolling out from under the strip
+func FadeColor(v types.Value, t float64) color.RGB {
+	_, base := TileGlyph(v, 0)
+	if t < parameter.ItemFlashFraction {
+		return color.White.Lerp(base, t/parameter.ItemFlashFraction)
+	}
+	u := (t - parameter.ItemFlashFraction) / (1 - parameter.ItemFlashFraction)
+	return base.Lerp(color.Black, u)
+}
+
+// FadeVisual adds the glyph collapse for the terminal strip: the item
+// glyph holds through the flash, then decays into the rail cell
+func FadeVisual(v types.Value, t float64) (rune, color.RGB) {
+	glyph, _ := TileGlyph(v, 0)
+	if t >= parameter.ItemFlashFraction {
+		u := (t - parameter.ItemFlashFraction) / (1 - parameter.ItemFlashFraction)
+		if i := int(u * float64(len(parameter.ItemFadeChars)+1)); i > 0 {
+			glyph = parameter.ItemFadeChars[min(i-1, len(parameter.ItemFadeChars)-1)]
+		}
+	}
+	return glyph, FadeColor(v, t)
+}
+
+// --- Nearest-occurrence blink ---
+
+// Blink pairs for the distance-row group of the tile(s) holding the grid-wide
+// nearest occurrence of each polarity. Both endpoints are high-luminance: the
+// cue must read as motion, not as a dip to the background
+var (
+	BlinkPositive = [2]color.RGB{color.White, color.BrightGreen}
+	BlinkNegative = [2]color.RGB{color.Yellow, color.BrightRed}
+)
+
+// BlinkColor selects the phase color of a pair. Phase is derived from the
+// wall clock, not from PlayDeltaZ: the cue must stay legible when the beat
+// tightens at higher levels
+func BlinkColor(pair [2]color.RGB, now time.Time) color.RGB {
+	return pair[(now.UnixNano()/int64(parameter.RenderBlinkPeriod))&1]
+}
+
+// --- Text composition (shared by both frontends) ---
+
+// TimerGlyphs is the wall-countdown affix set. The raylib default font
+// atlas covers 32..126 only, so it substitutes TimerASCII
+type TimerGlyphs struct{ Inbound, Clear, Open, Trap rune }
+
+var (
+	TimerUnicode = TimerGlyphs{
+		parameter.TimerInboundPrefix, parameter.TimerClearPrefix,
+		parameter.TimerOpenSuffix, parameter.TimerTrapSuffix,
+	}
+	TimerASCII = TimerGlyphs{'v', '^', '+', '!'}
+)
+
+// WallTimerText composes the wall countdown for a segment. Inbound
+// counts down to closure, clear counts down to the reopen chord. The trap
+// marker is not arrival-only: an inbound wall whose reopen gap is a trap is
+// flagged on approach. Returns "" when no wall is in the window
+func WallTimerText(g TimerGlyphs, s *game.GameState, seg game.WallSegment, now time.Time) (string, color.RGB) {
+	if seg.Distance < 0 {
+		return "", color.RGB{}
+	}
+
+	out := make([]rune, 0, 8)
+	fg := WallBandColor(seg.Distance)
+
+	if seg.Distance == 0 {
+		out = append(out, g.Clear)
+		out = append(out, []rune(TimerText(s.TimeToChordDistance(seg.Run, now)))...)
+		if seg.Open {
+			out = append(out, g.Open)
+		}
+		fg = color.White
+	} else {
+		out = append(out, g.Inbound)
+		out = append(out, []rune(TimerText(s.TimeToChordDistance(seg.Distance, now)))...)
+	}
+
+	if seg.Next && seg.Gap <= parameter.TrapGapMax {
+		out = append(out, g.Trap)
+	}
+	return string(out), fg
+}
+
+// TimerText formats a countdown as "S.s", clamped to
+// [0.0, 9.9]. Window * PlayDeltaZ stays under 10s at all levels; the clamp is a guard
+func TimerText(d time.Duration) string {
+	s := d.Seconds()
+	switch {
+	case s < 0:
+		s = 0
+	case s > 9.9:
+		s = 9.9
+	}
+	return fmt.Sprintf("%.1f", s)
+}
+
+// DistText formats a chord-distance into RenderDistDigits columns
+func DistText(d int) string {
+	if d < 0 {
+		return ""
+	}
+	return fmt.Sprintf("%d", min(d, 99))
+}
@@ -0,0 +1,40 @@
+package types
+
+import (
+	"time"
+
+	"symph/parameter"
+)
+
+// Note represents a single musical note
+type Note struct {
+	Value Value
+
+	// TODO: more properties to be added
+}
+
+// IsEmpty reports whether the Note has no content
+func (n Note) IsEmpty() bool { return n.Value == ValueNone }
+
+// IsWall reports whether the Note is a Wall obstacle
+func (n Note) IsWall() bool { return n.Value == ValueWall }
+
+// Chord represents a 3x3 grid of notes
+type Chord struct {
+	Notes [parameter.GamePlayIndexYMax][parameter.GamePlayIndexXMax]Note // 3x3 grid of notes
+}
+
+type Song struct {
+	Chords []Chord
+}
+
+// PlayerState holds the current playing position and temporal displacement state.
+// Lane (X) position is persistent; row (Y) displacement expires back to BaseIndexY
+type PlayerState struct {
+	ResetTime time.Time // When the current row displacement expires (Zero = no reset)
+
+	PlayIndexY int // Current Y coordinate
+	PlayIndexX int // Current X coordinate
+
+	BaseIndexY int // Resting row (returns here after jump/slide expiry)
+}
@@ -0,0 +1,122 @@
+package types
+
+import "fmt"
+
+// Value identifies the content of a Note. The enum is taxonomy only: per-kind
+// semantics live in valueSpecs, engine behavior in game.resolvers, appearance
+// in render.valueVisuals. No switch keys on a Value
+type Value int
+
+const (
+	ValueNone Value = iota
+	// Blocks
+	ValueWall
+	ValueSpike
+	// Force direction
+	ValueLeft
+	ValueDown
+	ValueUp
+	ValueRight
+	// Power up
+	ValueEnergy
+	ValueBoost
+	ValueShield
+	ValueMagnet
+	// Enemies
+	ValueDrain
+	ValueFortifiedLeft
+	ValueFortifiedDown
+	ValueFortifiedUp
+	ValueFortifiedRight
+	ValueFortifiedAll
+	// Count
+	ValueCount
+)
+
+// Polarity classifies a Value's effect on the player. Drives the
+// tile distance row (nearest help / nearest threat)
+type Polarity uint8
+
+const (
+	PolarityNeutral Polarity = iota
+	PolarityPositive
+	PolarityNegative
+)
+
+// ValueSpec is the static description of a Value — the single source of truth
+// for kind identity. Adding a kind is a row in valueSpecs, never a switch edit.
+// Glyph is both the pattern authoring rune and the fallback display glyph for
+// frontends limited to the 32..126 atlas; ASCII range and uniqueness are asserted
+type ValueSpec struct {
+	Name     string
+	Glyph    rune
+	Polarity Polarity
+}
+
+// valueSpecs is indexed by Value. Every kind below ValueCount needs a row
+var valueSpecs = [ValueCount]ValueSpec{
+	ValueNone: {"none", '.', PolarityNeutral},
+
+	ValueWall:  {"wall", '#', PolarityNegative},
+	ValueSpike: {"spike", 'x', PolarityNegative},
+
+	ValueLeft:  {"left", '<', PolarityNeutral},
+	ValueDown:  {"down", 'v', PolarityNeutral},
+	ValueUp:    {"up", '^', PolarityNeutral},
+	ValueRight: {"right", '>', PolarityNeutral},
+
+	ValueEnergy: {"energy", '*', PolarityPositive},
+	ValueBoost:  {"boost", 'B', PolarityPositive},
+	ValueShield: {"shield", 'S', PolarityPositive},
+	ValueMagnet: {"magnet", 'M', PolarityPositive},
+
+	ValueDrain:          {"drain", '~', PolarityNegative},
+	ValueFortifiedLeft:  {"fortified-left", 'L', PolarityNegative},
+	ValueFortifiedDown:  {"fortified-down", 'J', PolarityNegative},
+	ValueFortifiedUp:    {"fortified-up", 'K', PolarityNegative},
+	ValueFortifiedRight: {"fortified-right", 'R', PolarityNegative},
+	ValueFortifiedAll:   {"fortified-all", 'O', PolarityNegative},
+}
+
+// glyphValue is the reverse index consumed by the pattern parser
+var glyphValue map[rune]Value
+
+// Author errors (missing row, non-ASCII or duplicate glyph) are caught at
+// process start, matching parseChord
+func init() {
+	glyphValue = make(map[rune]Value, ValueCount)
+	for v := ValueNone; v < ValueCount; v++ {
+		s := valueSpecs[v]
+		switch {
+		case s.Name == "":
+			panic(fmt.Sprintf("types: Value %d has no spec row", int(v)))
+		case s.Glyph < ' ' || s.Glyph > '~':
+			panic(fmt.Sprintf("types: Value %d glyph outside ASCII 32..126", int(v)))
+		}
+		if _, dup := glyphValue[s.Glyph]; dup {
+			panic(fmt.Sprintf("types: glyph %q assigned twice", string(s.Glyph)))
+		}
+		glyphValue[s.Glyph] = v
+	}
+}
+
+// Valid reports whether v is a defined kind
+func (v Value) Valid() bool { return v >= ValueNone && v < ValueCount }
+
+// Spec returns the description of v; the None row when v is out of range
+func (v Value) Spec() ValueSpec {
+	if !v.Valid() {
+		return valueSpecs[ValueNone]
+	}
+	return valueSpecs[v]
+}
+
+func (v Value) Polarity() Polarity { return v.Spec().Polarity }
+func (v Value) Glyph() rune        { return v.Spec().Glyph }
+func (v Value) String() string     { return v.Spec().Name }
+
+// ValueByGlyph resolves an authoring rune to its Value
+func ValueByGlyph(r rune) (Value, bool) {
+	v, ok := glyphValue[r]
+	return v, ok
+}