feat: depth-of-field — soft-focus + dim the background (#11)

Pushes the background back so the speaker pops: a soft-focus blur + a dim behind the
sharp character. Viewer-local, OFF by default (Settings → "Depth of field").

- go-sdl2 exposes no per-texture scale mode, so a real linear-filtered downscale blur
  would need fragile global-hint juggling on the render thread. Instead the bg is
  soft-focused by SMEARING: the sharp bg plus eight low-alpha offset ghosts (reusing
  the outlineDirs ring, cardinals brighter than diagonals), then a dim overlay. The
  shared bg page's alpha is set per ghost and RESTORED to opaque. Replaces only the
  background draw — sprites/desk stay sharp. 0-alloc (cached page + scratch rect).
- SpriteFX.DoF flows via SetSpriteFX; config DepthOfField pref + Settings toggle.

Test: a 0-alloc render gate with DoF on. render+config+ui -race green;
BenchmarkRenderFrame still 0 allocs/op. Feature 7 of 10. (A true Gaussian blur is a
follow-up if the smear reads too subtle.)

Author: SyntaxNyah

internal/config/preferences.go

@@ -644,6 +644,7 @@ type AssetPreferences struct {
 	PostScanlines          bool                         `json:"postScanlines"`
 	PostGrain              bool                         `json:"postGrain"`
 	AnimateEntrances       bool                         `json:"animateEntrances"`
+	DepthOfField           bool                         `json:"depthOfField"`
 	FriendNotify           bool                         `json:"friendNotify"`
 	FriendOSToast          bool                         `json:"friendOSToast"`
 	CallwordOSToast        bool                         `json:"callwordOSToast"` // #M4 desktop toast on callword
@@ -858,6 +859,7 @@ type prefsJSON struct {
 	PostScanlines          bool             `json:"postScanlines"`          // default OFF
 	PostGrain              bool             `json:"postGrain"`              // default OFF
 	AnimateEntrances       bool             `json:"animateEntrances"`       // default OFF
+	DepthOfField           bool             `json:"depthOfField"`           // default OFF
 	SpriteTintColor        *int             `json:"spriteTintColor"`        // absent = default
 	FriendNotify           bool             `json:"friendNotify"`           // default OFF
 	FriendOSToast          bool             `json:"friendOSToast"`          // default OFF
@@ -1367,6 +1369,7 @@ func load(path string) (*AssetPreferences, error) {
 	p.PostScanlines = onDisk.PostScanlines
 	p.PostGrain = onDisk.PostGrain
 	p.AnimateEntrances = onDisk.AnimateEntrances
+	p.DepthOfField = onDisk.DepthOfField
 	if onDisk.SpriteTintColor != nil {
 		p.SpriteTintColor = *onDisk.SpriteTintColor & 0xFFFFFF
 	}
@@ -3275,6 +3278,17 @@ func (p *AssetPreferences) AnimateEntrancesOn() bool {
 // SetAnimateEntrances toggles the entrance slide-in.
 func (p *AssetPreferences) SetAnimateEntrances(on bool) { p.setBoolPref(&p.AnimateEntrances, on) }
 
+// DepthOfFieldOn reports the #11 toggle (OFF by default): soft-focus + dim the background
+// behind the sharp speaker.
+func (p *AssetPreferences) DepthOfFieldOn() bool {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.DepthOfField
+}
+
+// SetDepthOfField toggles the background depth-of-field.
+func (p *AssetPreferences) SetDepthOfField(on bool) { p.setBoolPref(&p.DepthOfField, on) }
+
 // setBoolPref sets *field to on under the lock, marking dirty only on a real change.
 func (p *AssetPreferences) setBoolPref(field *bool, on bool) {
 	p.mu.Lock()

internal/render/dof_test.go

@@ -0,0 +1,37 @@
+package render
+
+import (
+	"testing"
+	"time"
+
+	"github.com/veandco/go-sdl2/sdl"
+)
+
+// TestDepthOfFieldZeroAlloc pins #11: the background soft-focus + dim renders with zero
+// per-frame heap allocations (cached bg page + a scratch rect). Off → drawFill as before.
+func TestDepthOfFieldZeroAlloc(t *testing.T) {
+	ren, cleanup := newHeadlessRenderer(t)
+	defer cleanup()
+	store, err := NewTextureStore(ren)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer store.Purge()
+	for _, base := range []string{"bg", "desk", "spk", "pair"} {
+		if err := store.Upload(base, decodedFixture()); err != nil {
+			t.Fatal(err)
+		}
+	}
+	vp := NewViewport(store)
+	scene := benchScene(store)
+	vp.SetSpriteFX(SpriteFX{DoF: true})
+	rect := sdl.Rect{X: 0, Y: 0, W: 512, H: 384}
+
+	allocs := testing.AllocsPerRun(200, func() {
+		vp.Update(scene, 16*time.Millisecond)
+		vp.Render(ren, scene, rect)
+	})
+	if allocs != 0 {
+		t.Errorf("depth-of-field render allocates %.1f objects/op, want 0 (#11 zero-perf constraint)", allocs)
+	}
+}

internal/render/viewport.go

@@ -128,6 +128,7 @@ type SpriteFX struct {
 	Spin       bool // slow continuous rotation
 	ShoutPunch bool // #12: quick scale-pop of the whole stage when a shout appears
 	Entrance   bool // #9: slide the speaker in when a new character takes the stage
+	DoF        bool // #11: soft-focus + dim the background behind the sharp speaker
 
 	Speed     int // rainbow hue speed slider [1,100] (higher = faster)
 	Vividness int // rainbow saturation slider [0,100] (higher = more neon)
@@ -346,7 +347,11 @@ func (v *Viewport) Render(ren *sdl.Renderer, scene *courtroom.Scene, vp sdl.Rect
 		vp.Y += int32(amp / 2 * math.Cos(phase*1.3))
 	}
 
-	v.drawFill(ren, scene.BackgroundBase, &v.bgAnim, vp)
+	if v.fx.DoF {
+		v.drawBackgroundDoF(ren, scene.BackgroundBase, &v.bgAnim, vp) // #11 soft-focus + dim
+	} else {
+		v.drawFill(ren, scene.BackgroundBase, &v.bgAnim, vp)
+	}
 
 	// Pair hue offset for the "desync" effect: half a period so the two
 	// characters show opposite hues. Zero unless rainbow + desync are both on,
@@ -426,6 +431,52 @@ func (v *Viewport) drawFill(ren *sdl.Renderer, base string, anim *animState, vp
 	_ = ren.Copy(page.Frames[frame], nil, &v.fillRect)
 }
 
+// Depth-of-field tuning (#11). A real Gaussian needs per-texture linear filtering that
+// go-sdl2 doesn't expose, so the background is soft-focused by smearing it: the sharp bg
+// plus eight low-alpha offset ghosts (the outlineDirs ring), then a dim overlay to push it
+// behind the sharp speaker. All blits + a scratch rect → 0 alloc.
+const (
+	dofBlurDivisor = 90  // ghost offset = vp.H / divisor (floored)
+	dofBlurMin     = 3   //
+	dofAlphaCard   = 120 // cardinal ghost strength
+	dofAlphaDiag   = 80  // diagonal ghost strength
+	dofDimAlpha    = 95  // darkening over the blurred bg
+)
+
+// drawBackgroundDoF draws the background soft-focused + dimmed (#11). The bg store page's
+// alpha is set per ghost and RESTORED to opaque after (the page is shared T1). 0-alloc.
+func (v *Viewport) drawBackgroundDoF(ren *sdl.Renderer, base string, anim *animState, vp sdl.Rect) {
+	if base == "" {
+		return
+	}
+	page, ok := anim.resolve(v.store)
+	if !ok || len(page.Frames) == 0 {
+		return
+	}
+	tex := page.Frames[clampFrame(anim.frame, len(page.Frames))]
+	r := vp.H / dofBlurDivisor
+	if r < dofBlurMin {
+		r = dofBlurMin
+	}
+	v.fillRect = vp // the sharp base
+	_ = ren.Copy(tex, nil, &v.fillRect)
+	for i := range outlineDirs { // eight offset ghosts → a smear blur
+		a := uint8(dofAlphaCard)
+		if i >= 4 { // outlineDirs[4:] are the diagonals
+			a = dofAlphaDiag
+		}
+		_ = tex.SetAlphaMod(a)
+		v.fillRect = vp
+		v.fillRect.X += outlineDirs[i][0] * r
+		v.fillRect.Y += outlineDirs[i][1] * r
+		_ = ren.Copy(tex, nil, &v.fillRect)
+	}
+	_ = tex.SetAlphaMod(255)
+	v.fillRect = vp // dim overlay, pushing the bg behind the sharp speaker
+	_ = ren.SetDrawColor(0, 0, 0, dofDimAlpha)
+	_ = ren.FillRect(&v.fillRect)
+}
+
 // drawSprite draws a character layer: scaled to viewport height preserving
 // aspect, bottom-centered, shifted by percent offsets, optionally mirrored.
 // hueShift offsets this layer's rainbow phase (used to desync the pair).

internal/ui/app.go

@@ -3752,6 +3752,7 @@ func (a *App) spriteFX() render.SpriteFX {
 		Spin:       a.d.Prefs.SpriteSpinOn(),
 		ShoutPunch: a.d.Prefs.ShoutPunchOn(),
 		Entrance:   a.d.Prefs.AnimateEntrancesOn(),
+		DoF:        a.d.Prefs.DepthOfFieldOn(),
 		Speed:      a.d.Prefs.RainbowSpeed(),
 		Vividness:  a.d.Prefs.RainbowVividness(),
 	}

internal/ui/settings.go

@@ -643,6 +643,11 @@ func (a *App) drawSettingsGeneral(y, w int32) int32 {
 		a.d.Prefs.SetAnimateEntrances(next)
 	}
 	y += 26
+	dof := a.d.Prefs.DepthOfFieldOn()
+	if next := c.Checkbox(pad, y, "Depth of field (OFF by default): soft-focus + dim the background behind the speaker", dof); next != dof {
+		a.d.Prefs.SetDepthOfField(next)
+	}
+	y += 26
 	// Sprite hover-previews: rest the cursor on a character/emote button to pop a
 	// full-size preview. ON by default; the dwell before it shows is tunable.
 	prev := a.d.Prefs.SpritePreviewsOn()