# API widżetów: postMessage

Gra w iframe i strona rozmawiają wiadomościami w jednym formacie:

```js
{ pa: 1, typ: 'start' | 'pauza' | 'gotowa' | 'wynik', dane: {} }
```

| Kierunek | typ | dane | Kiedy |
|---|---|---|---|
| gra → strona | `gotowa` | `{ tytul }` | gra się załadowała |
| gra → strona | `wynik` | `{ wygrana, tekst, punkty? }` | koniec rundy (ekran wygranej albo przegranej) |
| strona → gra | `pauza` | `{}` | widżet wyjechał z ekranu albo strona tak chce |
| strona → gra | `start` | `{}` | widżet wrócił na ekran albo kliknięto start |

## Po stronie strony

```js
const gra = document.querySelector('pixel-gra');
gra.addEventListener('pixel-gra:wynik', (e) => console.log(e.detail)); // { wygrana: true, tekst: '...' }
gra.pauza();
gra.start();
```

Atrybut `towarzysz` (`<pixel-gra src="..." towarzysz>`) dodaje pod grą shih tzu, maskotkę pixelkamil. Podskakuje przy `gotowa` i `wynik`, przy wygranej mówi „Wygrana! Hau.”. Sprite jest wbudowany w `pixel-gra.js`, więc działa też na obcych stronach.

Zwykły iframe bez widżetu:

```js
const f = document.querySelector('iframe');
window.addEventListener('message', (e) => {
  if (e.source !== f.contentWindow || e.data?.pa !== 1) return;
  if (e.data.typ === 'wynik') console.log(e.data.dane);
});
f.contentWindow.postMessage({ pa: 1, typ: 'pauza' }, 'https://adres-gry.pl');
```

## Po stronie gry

- Gry na `lib/ekran.js` (`petla`, `nakladka`) mają to wbudowane: pauza zatrzymuje pętlę, `pokazKoniec()` wysyła `wynik`.
- Starsze gry dostają to jednym skryptem `widzety/most-gry.js` (pierwszy na stronie): owija `requestAnimationFrame` i `AudioContext`, więc pauza działa bez zmian w kodzie gry. Wynik: `window.pixelWynik({ wygrana: true, punkty: 12 })`.

## Bezpieczeństwo

- Gra odpowiada tylko oknu-rodzicowi (`e.source === window.parent`). Widżet przyjmuje tylko wiadomości ze swojej ramki i z originu gry (atrybut `origin` zawęża go ręcznie).
- Zero `eval`, zero inline skryptów i stylów: widżet działa przy CSP `script-src 'self'; style-src 'self'` (przykład: `widzety/index.html`).
- Gra z innej domeny: dodaj tę domenę do `frame-src` w CSP strony.