cedarwud/beamho-observer-sky-frontend

beamHO Observer-Sky Frontend

Use this skill for beamHO-bench/ when the task affects satellite display, observer-sky composition, god-view framing, display-set behavior, or frontend acceptance for Synthetic Orbit, Starlink TLE, and OneWeb TLE.

Read First

Read these first:

1. AGENTS.md
2. PROJECT_CONSTRAINTS.md
3. docs/zh-TW/07-observer-sky-visual-acceptance.md
4. sdd/completed/beamHO-bench-implementation-status.md
5. the current active pending frontend SDD
6. these frontend files:
   • src/components/scene/MainScene.tsx
   • src/components/scene/SatelliteSkyLayer.tsx
   • src/components/scene/ObserverSkyCameraRig.tsx
   • src/viz/satellite/view-composition.ts
   • src/viz/satellite/observer-sky-projection.ts
   • src/viz/satellite/display-selection.ts
   • src/viz/satellite/display-continuity.ts
   • src/viz/satellite/display-adapter.ts
   • src/viz/satellite/display-pipeline.ts
   • src/viz/satellite/screen-space-acceptance.ts

Ownership Boundaries

Keep these boundaries clear:

1. src/sim/**
   • physical/runtime truth
   • do not push frontend-only composition state back here
2. src/viz/satellite/**
   • projection, selection, continuity, composition, screen-space evaluation
3. src/components/scene/**
   • scene wiring, camera rig, accepted view-mode integration
4. src/components/sim/**
   • renderer-only display components

Do not solve a frontend acceptance problem by hiding more state inside runtime contracts.

Frontend Acceptance Rules

The result must satisfy docs/zh-TW/07-observer-sky-visual-acceptance.md.

In practice, that means:

1. satellites must read as rise -> pass -> set
2. elevation < 0 stays hidden
3. 0 <= elevation < theta_min stays ghost / non-serving
4. elevation >= theta_min reads as active
5. screen-space must not collapse into a center-top cluster
6. satellites must remain identifiable as continuous moving objects
7. display set must remain broader than HO candidate set when the physical pool allows it

Do not mark complete if the screen still reads as:

1. a pack of points near the scene center swapping places
2. long pauses followed by abrupt relocation
3. candidate-limit-driven top-N truncation in the visible sky

Preferred Change Surfaces

Typical frontend fixes belong in:

1. src/viz/satellite/view-composition.ts
2. src/viz/satellite/display-selection.ts
3. src/viz/satellite/display-continuity.ts
4. src/viz/satellite/display-adapter.ts
5. src/viz/satellite/display-pipeline.ts
6. src/viz/satellite/screen-space-acceptance.ts
7. src/components/scene/ObserverSkyCameraRig.tsx
8. src/components/scene/MainScene.tsx
9. src/components/scene/SatelliteSkyLayer.tsx

Do not reach for generic camera-distance tweaks first if the actual problem is display selection, composition policy, or continuity semantics.

Validation

For observer-sky frontend work, prefer this full set:

1. npm run lint
2. npm run test:sim
3. npm run build
4. npm run validate:stage

Also check whether tests cover:

1. screen-space spread
2. pass readability
3. continuity readability
4. cross-mode consistency

If those tests are missing for the change, add them instead of relying on manual claims alone.

Closure Rule

Frontend observer-sky work is not closure-ready until:

1. automated validation passes
2. manual acceptance is checked against docs/zh-TW/07-observer-sky-visual-acceptance.md
3. lifecycle docs are synced
4. the result is not justified only by proxy metrics such as:
   • sector diversity
   • determinism
   • retained-ID counts

Reporting

Always report:

1. which frontend layers changed
2. whether camera/composition or display-set policy changed
3. what automated validation ran
4. whether manual visual acceptance was actually checked
5. what still fails if the screen is not yet acceptable