feat: add adaptive visual governor (#99)

Author: hyeonsangjeon

AGENTS.md

@@ -49,6 +49,7 @@ CDN import map (Three.js r0.160 via jsDelivr) plus local data, scripts, and modu
 | **`scripts/build_repos.py`** | Rebuilds `repos.json` and `data/city-state.json` from `data/logs/*` traffic + `gh api`. | Refreshing the city data locally. |
 | **`scripts/resident_profiles.py` + `data/residents/`** | Generates sanitized public resident profiles, the boot manifest, and the Worker authority registry. Profile JSON is generated — do not hand-edit. | Changing repository-bound resident identity or Shared/Bound inputs. |
 | **`scripts/smoke.mjs`** | Hermetic static and behavioral regression guards for the city runtime. | Any client feature, navigation, or generated-module integration change. |
+| **`scripts/test-visual-governor.mjs`** | Extracts and deterministically replays the inline adaptive visual-governor core. | Changing warm-up, thresholds, hysteresis, dwell, LOW_END/reduced-motion bounds, or recovery. |
 | **`scripts/test-portable-town.mjs`** | Deterministic fixtures for canonical, foreign, empty/archive-only, partial, missing-date, leakage, resident-cap, and zero-request portable towns. | Changing public-town projection or local resident derivation. |
 | **`.github/workflows/refresh.yml`** | "Refresh Repolis data" — daily Action that regenerates `repos.json` and pushes `chore: refresh`. | CI / data-refresh changes. |
 | **`scripts/build-contribution-library.mjs` + `assets/contribution-library.json`** | Generates the in-app **Contribution Library** JSON from the sibling `Hyeonsang-AI-Contributions` README (KO/EN); `index.html` fetches it at runtime. JSON is **generated — do not hand-edit.** Daily via `.github/workflows/update-contribution-library.yml`. | Changing the library landmark's data/source. |
@@ -127,6 +128,7 @@ zero LLM, zero cost — so run them freely:
 node council/test.mjs        # deterministic Council crosscheck
 node council/test-live.mjs   # live guards + state machine
 node scripts/smoke.mjs       # city/runtime static + behavioral regression guards
+node scripts/test-visual-governor.mjs
 node scripts/test-portable-town.mjs
 python3 scripts/test_city_state.py
 python3 scripts/validate_city_state.py
@@ -181,6 +183,7 @@ Tested on Node v24. There is no linter or formatter configured — match the sur
 | Change Creator Hall profile facts, caching, or upstream Star handoff | `assets/town-creator.js` + the Creator Hall landmark/panel blocks in `index.html` + `scripts/smoke.mjs`; keep profile loading explicit-read and allowlisted. |
 | Change Town Growth Replay years, camera, reveal, share links, or era postcards | `assets/town-growth.js` + `/*TOWN_GROWTH_REPLAY*/` in `index.html` + the Growth Replay group in `scripts/smoke.mjs`; creation dates are historical, building metrics are current, and replay must restore camera/fog/sky/LOD exactly. |
 | Change Repository Atelier room, avatar, data walls, or action terminals | `/*REPOSITORY_ATELIER*/` in `index.html` + the Atelier group in `scripts/smoke.mjs`; preserve one lazy reusable room, three bounded canvas atlases, exact exterior restore, zero exterior renders inside, in-room Ask/Why ownership, and explicit-only exit/GitHub navigation. |
+| Change adaptive frame thresholds or visual tiers | `/*VISUAL_GOVERNOR_CORE*/` + `/*VISUAL_GOVERNOR_RUNTIME*/` in `index.html`, `scripts/test-visual-governor.mjs`, and the matching smoke group; preserve 6 s eligible warm-up, separated hysteresis/dwell, balanced-before-lean ambient ordering, LOW_END/reduced-motion authority, state continuity, and zero storage/network/telemetry. |
 | Change Twin Towns matching or two-person share links | `assets/twin-towns.js` + the Twin Towns block in `index.html` + `scripts/smoke.mjs`. |
 | Change Town Gazette / return-visit freshness | `/*FRESHNESS*/` + Passport render/start flow in `index.html`; keep snapshots local, bounded, per-town, and explicit-read only. |
 | Change resident homes, styles, gardens, routines, moods, friendships, haunts, or Shared Joy | The resident social layer + Starlight Row blocks in `index.html`; preserve the resident style map, 3 roof batches, 10/6 desktop/LOW_END detail-batch cap, 42-unit reserve, entrance gap, quarter colliders, home/work truth, owned porch seats, and social ownership guards. |

CHANGELOG.md

@@ -6,6 +6,29 @@ The format loosely follows [Keep a Changelog](https://keepachangelog.com/); date
 This file keeps the current product era (`1.50.0` onward) easy to scan. Earlier releases are preserved in
 [`docs/changelog-archive.md`](docs/changelog-archive.md).
 
+## [1.93.0] — 2026-08-26
+
+### 🎛️ Adaptive Visual Governor — preserve detail within the frame budget
+
+- A three-tier `full` / `balanced` / `lean` governor now observes eligible active render intervals only after
+  6,000 ms of warm-up. Full steps down after a 22.5 ms EMA holds for 3,000 ms; balanced steps down after
+  28.5 ms holds for 5,000 ms. Recovery uses separate 18.5/17.5 ms thresholds, 18,000/14,000 ms evidence,
+  and 14,000/10,000 ms tier dwell so quality returns one step at a time without flicker.
+- Balanced cuts distant building-shadow proxies, particle draw ranges, decorative update cadence, and World Tree
+  bloom cadence first. Lean tightens those bounds and only then biases existing far-building LOD. Repository
+  signs, silhouettes, colliders, functional roots, nearby full detail, and camera/control ownership remain intact.
+- Hidden, idle-capped, intro, modal, Atelier, and Growth Replay frames do not enter evidence. Existing LOW_END
+  clamps the quality ceiling to balanced, and reduced motion keeps decorative cadence at zero through debug force
+  and recovery. Residents, social routines, tours, taxi rides, Atelier, Growth Replay, and Chronicle state are
+  observed but never reset.
+- `?dbg` exposes `window.__visualGovernor()` with force/auto, deterministic low/recover/hidden/transient fixtures,
+  replay, work counts, and continuity state. The helper is in-memory only: no telemetry, persistence, request,
+  backend, model call, dependency, build step, or asset was added.
+- Controlled owner-night diagnostics measured full/balanced/lean shadow proxies at 69/46/23, particles at
+  3,473/2,363/1,459, bloom ceilings at 30/20/12 Hz, and draw calls at 2,481.67/2,465.83/2,417.33. Cold-load requests
+  remain owner 31→31 and foreign 27→27 (the existing foreign GitHub read stays one); decoded same-origin bytes
+  rise by 13,825 (owner 1,726,282→1,740,107; foreign 1,629,433→1,643,258).
+
 ## [1.92.0] — 2026-08-26
 
 ### 🌳 Portable Living Towns — public records grow their own local life

docs/known-limitations.md

@@ -101,6 +101,12 @@ change around a constraint that can't move. Pair this with [`AGENTS.md`](../AGEN
 - **No full browser automation suite.** `scripts/smoke.mjs` guards many static and extracted behavioral
   contracts, but visual and interaction changes still require serving locally and driving the page in
   Chrome DevTools with 0 console errors on mobile + desktop.
+- **Adaptive quality is an in-memory safety rail, not a benchmark or device profile.** The governor observes
+  visible, active exterior render intervals only after 6 seconds of eligible warm-up, uses three coarse reversible
+  tiers, and forgets everything on reload. Hidden tabs, the intentional idle cap, intro/modals, Atelier, and Growth
+  Replay do not influence it. LOW_END remains the maximum quality bound and reduced motion keeps decorative
+  updates stopped; there is no user dashboard, telemetry, persistence, fingerprint, backend report, or attempt to
+  predict hardware. `?dbg` fixtures are local deterministic replays rather than real-device speed claims.
 - **Owner-town size is a snapshot, not a contract.** Its repository count changes whenever the daily
   public data refresh adds, removes, or filters a repository.
 - **Town Gazette is browser-local.** It compares public repo fields against the last snapshot marked read