# Story: A Background That No Longer Moves — Only Fading Light

**Phase:** `25_background_no_motion` · **E2E:**
`tests/e2e/test_background_no_motion.py`
**Supersedes:** `.agent/user_stories/background-animation.md`
(phase-22 motion design — history preserved there)

## Narrative

As **the owner**, I reported (2026-08-25, chat) that the phase-22
background "jitters down and to the right every second and it slowly
blinks brighter and darker". I want the background to be smooth,
fluxuating, dimming and brightening — but **not moving** — with
**different bright spots** that slowly fade in and out.

- **Given** the phase-22 animated background (a 60s one-cell grid drift
  at 0.73px/s diagonally down-right + a 14s whole-layer glow breathe of
  opacity 0.85↔1 with scale 1↔1.05)
- **When** the page is observed in a real Chromium viewport
- **Then** nothing moves — the grid is a static texture and no
  background keyframe animates anything but `opacity` — while three
  independent bright spots each fade in and out on their own slow,
  out-of-phase cycles (26s/34s/42s), so the total light fluxuates
  smoothly and irregularly: no jitter, no blink, no static frame, no
  new overflow at 360px, and no impact on text contrast or
  interactivity.

## Owner report (verbatim, 2026-08-25, chat)

> It should be smooth, fluxuating, dimming and brightening, but not
> moving. Different bright spots should slowly fade in and out.

## Owner direction (2026-08-25)

1. **No movement** — no grid drift, no `scale`/`transform`, no
   `background-position` animation, anywhere in the background.
2. **Fluxuating brightness** — overall page brightness varies smoothly
   and irregularly (not one synchronized pulse).
3. **Different bright spots** — multiple glow spots, each fading in
   and out on its own slow cycle.
4. **The static grid stays** — the owner rejected the grid's *motion*,
   not the grid; it remains as a still texture. (If the owner later
   wants the grid gone, that is a follow-up, not this phase.)

## Root cause (found from the code + phase-22 measurements)

1. **"Jitters down and to the right every second" = the grid drift.**
   `bg-grid-drift` moved the 44px grid 44px per 60s (≈0.73px/s)
   diagonally down-right — exactly the reported direction. A 1px grid
   line translated sub-pixel by sub-pixel is rasterized with per-frame
   stepping/shimmer, not smooth motion: it reads as a once-per-second
   jitter. Phase 22 had made that drift *visible* (60% line alpha,
   wider mask — measured 1.82/765 mean pixel change over 5s in the
   grid zone); that is precisely why it now reads as jitter.
2. **"Slowly blinks brighter and darker" = the whole-layer breathe.**
   `bg-glow-breathe` swung the ENTIRE glow layer's opacity 0.85↔1 over
   14s (alternate) plus `scale(1)↔scale(1.05)` (a faint zoom). One
   synchronized pulse of the whole background reads as a blink; the
   owner wants independent spots instead.

Phase 22 served the phase-08 design intent (grid drift + whole-layer
breathe). The owner's 2026-08-25 direction supersedes that **design
intent** — no LOCKED anchor changed (A11 stays pure CSS / zero JS / no
CDN / no new assets; the no-`filter: blur` perf anchor is honored).

## Fix (styles.css — pure CSS, zero JS, no blur, palette untouched)

| property | phase 22 | phase 25 |
|---|---|---|
| grid (`body::before`) | `bg-grid-drift 60s linear infinite` (0→44px) | **static** — no animation, `bg-grid-drift` deleted (44px cells, 60% `--line` 1px lines, widened mask kept) |
| glow layer count | one whole-layer breathe | **three independent spot layers** |
| spot A (`body::after`) | indigo + cyan spots, 14s opacity 0.85↔1 + scale 1↔1.05 | **indigo `rgb(109 120 242 / 0.14)` 56rem at 12%/8%**, `bg-glow-a` **26s** ease-in-out infinite, low opacity **0.25** |
| spot B (`html::before`) | — (cyan shared body::after) | **cyan `rgb(34 211 238 / 0.10)` 60rem at 88%/92%**, `bg-glow-b` **34s** ease-in-out **−12s** infinite, low **0.20** |
| spot C (`html::after`) | — | **indigo `rgb(109 120 242 / 0.09)` 52rem at 14%/86%**, `bg-glow-c` **42s** ease-in-out **−23s** infinite, low **0.15** |
| keyframes | `bg-grid-drift` (background-position), `bg-glow-breathe` (opacity + transform) | **`bg-glow-a/b/c` — opacity only** (0%/100% low → 50% 1) |
| reduced motion | stills `body::before/::after` | stills **all four** layers |

All four layers keep `content: ""; position: fixed; inset: 0;
z-index: -1; pointer-events: none`. `<html>` keeps the `var(--bg)`
canvas and `<body>` stays transparent (the no-occlusion contract):
`html` is the root stacking context, so its `z-index: -1`
pseudo-elements paint above the canvas and below the transparent,
non-stacking `<body>`'s content. The 26/34/42s periods with negative
delays (LCM 4641s) keep the cycles out of phase — the composite
pattern effectively never repeats within a viewing session.

## Acceptance criteria
1. **No movement:** the grid is static (`body::before` computed
   `animationName: none`; no `bg-grid-drift` in
   `document.getAnimations()`; grid texture still painted) and —
   audited in real Chromium via `document.styleSheets` — **no `bg-*`
   keyframe animates anything but `opacity`** (the deterministic
   no-movement proof).
2. **Three distinct bright spots** (`body::after`, `html::before`,
   `html::after`) run distinct slow opacity fades (26s/34s/42s,
   ease-in-out, infinite, pairwise distinct, out of phase); all three
   timelines advance; the layer's computed opacity AND a clipped
   screenshot of the bottom-left glow region measurably change within
   a few seconds (a real fade, not a frozen frame).
3. **Contracts hold:** all four layers `position: fixed`, `z-index:
   -1`, `pointer-events: none`, full-viewport `inset: 0`; `<html>`
   keeps the `var(--bg)` canvas (`rgb(10, 14, 23)`) and `<body>` stays
   transparent (`rgba(0, 0, 0, 0)`) — no occlusion.
4. **Reduced motion** stills all four layers
   (`animationName: none`), the static grid + spot images remain.
5. No new horizontal overflow at 360px (the phase-07 pin).
6. Pure CSS, zero JS, no `filter: blur`, no new assets (A11 + phase-08
   perf anchor); WCAG AA palette untouched (the layers carry no text).
7. Regressions green in isolation:
   `tests/e2e/test_background_animation.py` (adapted to the phase-25
   contract), `tests/e2e/test_dark_tech_theme.py` (grid static +
   26/34/42s spots; reduced motion across all four layers),
   `tests/e2e/test_responsive_polish.py`.
8. Unit + integration green, `app/` coverage >90%, story E2E green in
   isolation, ruff + pyright clean.

## UI Visualization & Structure
- **Grid layer (`body::before`):** 44px cells, 1px lines at 60% of
  `--line` (`rgb(38 48 74 / 0.6)`), widened radial mask
  (`140% 110% at 50% 0%, black 40%, transparent 90%`) — a STATIC
  texture, no animation.
- **Glow spot A (`body::after`):** indigo `rgb(109 120 242 / 0.14)`
  56rem circle at 12%/8% (phase-08 position/color); opacity-only fade
  0.25↔1 over 26s ease-in-out.
- **Glow spot B (`html::before`):** cyan `rgb(34 211 238 / 0.10)` 60rem
  circle at 88%/92% (phase-08 position/color); fade 0.20↔1 over 34s,
  −12s delay.
- **Glow spot C (`html::after`):** indigo `rgb(109 120 242 / 0.09)`
  52rem circle at 14%/86%; fade 0.15↔1 over 42s, −23s delay.
- **Stacking / no occlusion:** the `<html>` canvas
  (`var(--bg)` = `#0a0e17`) sits under all four `z-index: -1` layers;
  `<body>` stays transparent and non-stacking, so nothing can paint
  over the layers — verified live, not assumed.
- **Motion:** opacity-only keyframes (compositor-friendly); no
  `transform`, no `background-position`, no `filter` anywhere in the
  background; `prefers-reduced-motion: reduce` stills all four layers
  (the static background remains visible).

## Playwright Mapping Rule
**Test Scenario → `tests/e2e/test_background_no_motion.py`** (the
layers are CSS pseudo-elements — asserted via computed style + the Web
Animations API + a live `document.styleSheets` audit; Chromium
enumerates pseudo-element CSS animations in `document.getAnimations()`,
not `document.body.getAnimations()`, and the `html` pseudo-layers'
computed styles come from
`getComputedStyle(document.documentElement, "::before"/"::after")`):
1. `test_grid_layer_is_static` — computed `animationName` of
   `body::before` is `"none"`; no `bg-grid-drift` entry in
   `document.getAnimations()`; the grid `backgroundImage` is still
   present (the static texture survives).
2. `test_three_glow_layers_run_distinct_fades` — `body::after` →
   `bg-glow-a` (26s), `documentElement::before` → `bg-glow-b` (34s),
   `documentElement::after` → `bg-glow-c` (42s); each `ease-in-out` +
   `infinite`, with a matching `playState === "running"` entry in the
   document animation list; the three durations are pairwise distinct.
3. `test_no_motion_properties_in_background_keyframes` — walk
   `document.styleSheets`; for every `CSSRule.KEYFRAMES_RULE` whose
   name starts with `bg-`, collect the declared property names of
   every keyframe frame; the set across all frames is exactly
   `{"opacity"}` — the deterministic no-movement proof.
4. `test_glow_timelines_advance` — poll until all three timelines
   report `currentTime > 0` (headless Chromium starts the document
   timeline ~1s after load), sample all three, wait ~500ms, each
   advanced ≥ 200ms.
5. `test_background_light_actually_changes` — (a) the computed opacity
   of `body::after` changes by ≥ 0.05 within ~8s (a real fade, not a
   frozen frame); (b) two clipped screenshots ~4s apart of the
   bottom-left glow region (the `html::after` spot at 14%/86%) differ
   in bytes — the light visibly changes while nothing moves.
6. `test_background_layers_contracts` — all four pseudo-layers:
   `position: fixed`, `z-index: -1`, `pointer-events: none`,
   top/right/bottom/left all `0px`; `documentElement` computed
   background is `rgb(10, 14, 23)` (canvas stays on `html`);
   `document.body` computed background is `rgba(0, 0, 0, 0)` (no
   occlusion).
7. `test_reduced_motion_stills_all_layers` —
   `reduced_motion="reduce"` context: all four pseudo-layers report
   computed `animationName` `"none"` and still carry a
   `backgroundImage`.
8. `test_no_horizontal_overflow_with_layers` — 360px viewport:
   `documentElement.scrollWidth <= clientWidth` (the phase-07 pin).