skills/docs/requirements/002-cosmos.md

# 002 - Cosmos

## User Story

As the operator and the designer, I want the orchestrator's sky, music and
orbit scene as one reusable component behind a small live globe, so that the
orchestrator and every Infinito.Nexus web app can show the same calm
background without carrying its code twice.

## Decisions (operator-confirmed 2026-11-06; do not re-litigate)

1. **Scope**: everything of the orchestrator's background moves: the sky (sun,
   moon, stars, twilight stages, day and night palettes with contrast check),
   the generated meditative music and the orbit and 3D scene. The radio
   streams with their schedule stay in the orchestrator. Rejected: the sky
   only.
2. **Repository**: `github.com/kevinveenbirkenbach/cosmos`, not managed by
   pkgmgr, laid out as an Infinito.Nexus custom role `web-app-cst-cosmos` that
   core pulls from its inventory-declared source. Rejected: the infinito-nexus
   organisation, a pkgmgr-managed release.
3. **Form**: Web Components (`<cosmos-ambience>` for sky and music,
   `<cosmos-graph>` for the 3D scene) that also set `--cosmos-*` CSS custom
   properties every design can follow; a "colors only" mode draws nothing.
   Rejected: a plain ES module.
4. **Globe menu**: a small globe logo turns with the Earth's real rotation and
   shows the current Earth with its live day and night line; a click on it
   reveals every control, nothing else is visible while it is closed.
   Rejected: a visibly spinning globe (not the real orientation).
5. **Licence**: MIT, like the skills repository it comes from. Rejected: the
   Infinito.Nexus Community License (non-commercial, limits reuse).
6. **Work split**: Skills extracts the code into cosmos and switches the
   orchestrator to a pinned cosmos version; the IAM agent builds the core
   integration: a role that the design service `web-svc-design` activates.
   Rejected: IAM doing everything.
7. **Timing**: implemented after requirement 001; the core part also needs
   core's custom roles (requirement 046) on core main. Rejected: starting now.
8. **Icons**: the controls use Bootstrap Icons per decision 19 of
   requirement 001.

## Approach

```mermaid
flowchart TD
    subgraph P["🧭 0 · Preparation"]
        P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
        P2 -- "✏️ corrections" --> P1
        P2 -- "🤖 yes" --> P3{"🏁 001 done and 046 on core main?"}
        P3 -- "⏳ not yet" --> P3
    end
    P3 -- "🟢 yes" --> C1
    subgraph C["🌌 1 · Extract into cosmos (Skills)"]
        C1["🔴 Red tests: astronomy, palette contrast, globe, attributes"] --> C2["🛠️ cosmos repo as custom role, Web Components, globe menu, demo page"]
        C2 --> C3{"🧪 Tests and core role lints green?"}
        C3 -- "🔴 no: fix" --> C2
        C3 -- "🟢 yes" --> C4["📸 Screenshots: noon, dusk, night, menu open"]
        C4 --> CF{"💬 Operator feedback?"}
        CF -- "✏️ changes" --> C2
    end
    CF -- "👍 commit word" --> O1
    subgraph O["🧭 2 · Orchestrator on cosmos (Skills)"]
        O1["🔁 Pin cosmos, drop ambience.js, sky and generated music"] --> O2{"🧪 Orchestrator tests green?"}
        O2 -- "🔴 no: fix" --> O1
        O2 -- "🟢 yes" --> OF{"💬 Operator feedback?"}
        OF -- "✏️ changes" --> O1
    end
    OF -- "👍 commit word" --> I1
    subgraph I["🏛️ 3 · Core integration (IAM)"]
        I1["📋 IAM writes the core requirement"] --> I2["🛠️ Role activated by web-svc-design"]
        I2 --> I3{"🧪 Deploy and Playwright green?"}
        I3 -- "🔴 no: fix" --> I2
        I3 -- "🟢 yes" --> IF{"💬 Operator feedback?"}
        IF -- "✏️ changes" --> I2
    end
    IF -- "👍 fits" --> D1["🏁 Commit with operator OK, push hand-over"]
```

## Acceptance Criteria

### Repository

- [ ] `github.com/kevinveenbirkenbach/cosmos` holds an MIT `LICENSE`.
- [ ] `pkgmgr list` does not list cosmos.
- [ ] The repository is a role named `web-app-cst-cosmos`: `README.md`,
      `meta/` (main, info, services, license), `tasks/main.yml`, and the
      components under `files/`.
- [ ] An inventory group `web-app-cst-cosmos` with `custom: true` and a
      pinned source makes core's `make roles-pull` place it.
- [ ] Every core role lint passes on the placed role.

### Components

- [ ] `<cosmos-ambience>` takes `latitude`, `longitude`, `mode`
      (`full` or `colors`) and `music` with a volume, and follows
      `prefers-reduced-motion`.
- [ ] It sets `--cosmos-sky-top`, `--cosmos-sky-bottom`, `--cosmos-stage` and
      `--cosmos-text` and updates them at least once a minute.
- [ ] Text against sky keeps a contrast of at least 4.5:1 at every minute of a
      day at 0° N 0° W and at 52.5° N 13.4° E (unit test).
- [ ] Sun and moon positions match published reference values within 1° for
      at least six fixed dates (unit test).
- [ ] `<cosmos-graph>` renders the 3D scene on vendored `3d-force-graph`
      1.80.1 and `three` 0.186.1 and takes nodes and links as data.
- [ ] The generated meditative music plays with a volume; no radio stream
      code is in the repository.

### Globe menu

- [ ] A globe of at most 48 px shows a public-domain Earth texture with the
      live day and night line, turned to the Earth's current rotation.
- [ ] A click, Enter or Space opens the control panel and Esc closes it.
- [ ] While the panel is closed only the globe is visible.
- [ ] Every control is a Bootstrap Icon with `title` and `aria-label`.

### Orchestrator

- [ ] The orchestrator vendors a pinned cosmos tag and loads it under its
      nonce CSP.
- [ ] `ambience.js`, the sky code and the generated music are gone from the
      orchestrator; its radio-stream schedule stays.
- [ ] The orchestrator's 3D views render through `<cosmos-graph>`.

### Core (IAM)

- [ ] IAM writes the core requirement for the integration.
- [ ] With `web-svc-design` activating cosmos, a designed web app shows the
      cosmos background behind its content with the globe.
- [ ] With it off, the app loads no cosmos file.

### Tests

- **Unit**
  - [ ] Astronomy against reference values.
  - [ ] Palette contrast over a day.
  - [ ] Attribute parsing.
  - [ ] Globe orientation at fixed times.
- **Integration**
  - [ ] Core's `make roles-pull` places cosmos and its role lints pass.
  - [ ] The orchestrator serves the pinned cosmos under its CSP.
- **E2E**
  - [ ] Headless Chromium and Firefox open the cosmos demo page and the
        orchestrator at noon, dusk and night with the menu closed and open,
        and save the screenshots.
  - [ ] One designed core app is opened with cosmos on and off.