Overlay: fuenf Browser-Sources fuer OBS

Einblendungen, Chat, Statusleiste, Effekte, Pausenbild. Kein Build, kein
Framework - OBS laedt die Dateien direkt, und jede Zwischenstufe waere ein
Ding, das mitten im Stream kaputtgehen kann.

Server-Sent Events statt WebSocket, entgegen der Skizze in chat-control.md:
Node bringt einen WebSocket-*Client* mit, aber keinen Server, `EventSource`
verbindet sich von allein neu, und die Richtung stimmt - das Overlay hoert
nur zu. Gegen die tote Browser-Source nach einem Neustart stehen drei Dinge:
der eingebaute Reconnect, ein Herzschlag als echtes Ereignis (ein
SSE-Kommentar haelt die Verbindung offen, ist im Browser aber unsichtbar),
und ein Zustands-Schnappschuss beim Verbinden.

Abos, Raids, Bits und Loeschungen kommen ueber IRC-USERNOTICE und CLEARCHAT
herein; das wurde bisher weggeworfen. Follows fehlen weiter, die gibt es nur
ueber EventSub.

GIFs im Chat: Twitch schickt dafuer einen Tag `gifs`, den wir nicht kannten.

  gifs=0-22|Pnd7qLFuGCOntZcNKB|https://media0.giphy.com/media/.../giphy.gif
  PRIVMSG #abdulive_ :[Idk GIF by Respective]

Der Nachrichtentext ist nur ein Platzhalter, der Bereich markiert ihn.
Ausgewertet wird er jetzt; ohne das stand woertlich "[Idk GIF by Respective]"
im Bild. Gefunden wurde der Tag durch einen Rohmitschnitt - in 3094
Nachrichten aus acht grossen Kanaelen war kein einziges GIF, weil die Adresse
eben nicht im Text steht.

Zwei Fehler, die beim Durchklicken im Browser aufgefallen sind:

- Die Aufraeumfunktion im Chat zaehlte Zeilen, die erst nach der
  Ausblend-Animation aus dem DOM verschwinden, und lief in eine
  Endlosschleife. In OBS waere die Quelle beim vierzehnten Chatbeitrag
  eingefroren.
- Der Bereichsparser der GIFs war zu nachsichtig: `-1-4` zerfaellt beim
  Trennen in ['', '1', '4'], und `Number('')` ist 0 - der Bereich saehe
  gueltig aus und wuerde den falschen Textteil ersetzen.

Auf der Uebersichtsseite steht fuer jede Einblendung, jede Chat-Variante und
jeden Effekt ein Knopf. Ohne den liesse sich eine Raid-Einblendung nur
pruefen, indem man auf einen echten Raid wartet. Was einen Zustand setzt, ist
waehrend eines Streams gesperrt; "Stand zuruecksetzen" ausdruecklich nicht,
sonst kaeme man aus einem erfundenen Zustand nicht mehr heraus.

build-package.ts nimmt jetzt auch html/css/js mit - sonst liefert das Paket
404 statt Overlay.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

packages/twitch/src/irc.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { parseLine, toChatMessage } from './irc.ts';
+import { parseLine, toChatMessage, parseGifs } from './irc.ts';
 
 const LINE =
   '@badge-info=subscriber/8;badges=broadcaster/1,subscriber/6;color=#1E90FF;' +
@@ -57,3 +57,50 @@ test('PING wird als solches erkannt', () => {
   assert.equal(m?.command, 'PING');
   assert.equal(m?.params[0], 'tmi.twitch.tv');
 });
+
+// ---------------------------------------------------------------- GIFs
+
+test('der gifs-Tag wird zerlegt', () => {
+  // Echte Zeile aus #abdulive_, mitgeschnitten am 2026-09-17.
+  const g = parseGifs(
+    '0-22|Pnd7qLFuGCOntZcNKB|https://media0.giphy.com/media/Pnd7qLFuGCOntZcNKB/giphy.gif?cid=095d&ct=g');
+  assert.equal(g.length, 1);
+  assert.equal(g[0]!.id, 'Pnd7qLFuGCOntZcNKB');
+  assert.equal(g[0]!.from, 0);
+  assert.equal(g[0]!.to, 22);
+  assert.match(g[0]!.url, /^https:\/\/media0\.giphy\.com\//);
+  assert.ok(g[0]!.url.includes('&ct=g'), 'die Adresse darf nicht am & abgeschnitten werden');
+});
+
+test('der Bereich deckt genau den Platzhalter ab', () => {
+  // Wenn das nicht stimmt, bleibt ein Rest der eckigen Klammer im Bild stehen.
+  const text = '[Idk GIF by Respective]';
+  const g = parseGifs('0-22|abc|https://x/y.gif')[0]!;
+  assert.equal([...text].slice(g.from, g.to + 1).join(''), text);
+});
+
+test('eine Nachricht ohne GIF hat eine leere Liste', () => {
+  const m = parseLine('@id=1;user-id=7;emotes= :a!a@a PRIVMSG #k :moin');
+  assert.deepEqual(toChatMessage(m!)!.gifs, []);
+});
+
+test('eine Nachricht mit GIF traegt es bis in die ChatMessage', () => {
+  const m = parseLine(
+    '@id=1;user-id=7;emotes=;gifs=0-4|xy|https://media.giphy.com/a.gif ' +
+    ':a!a@a PRIVMSG #k :[GIF]');
+  assert.equal(toChatMessage(m!)!.gifs[0]!.url, 'https://media.giphy.com/a.gif');
+});
+
+test('kein https, kein Bild', () => {
+  // Der Tag kommt von Twitch, nicht vom Chatter - trotzdem landet die Adresse
+  // als Bild im Stream, und dort gilt kein Vertrauensvorschuss.
+  assert.deepEqual(parseGifs('0-4|xy|http://media.giphy.com/a.gif'), []);
+  assert.deepEqual(parseGifs('0-4|xy|javascript:alert(1)'), []);
+});
+
+test('unvollstaendige oder unsinnige Tags werden verworfen', () => {
+  for (const kaputt of ['', '0-4', '0-4|nurid', 'abc|x|https://y/z.gif', '-1-4|x|https://y/z.gif',
+                        '9-4|x|https://y/z.gif']) {
+    assert.deepEqual(parseGifs(kaputt), [], `"${kaputt}" haette verworfen gehoert`);
+  }
+});

packages/twitch/src/irc.ts

@@ -52,6 +52,48 @@ export function parseLine(line: string): IrcMessage | null {
   return { tags, prefix, command, params: parts };
 }
 
+/**
+ * Der `gifs`-Tag. Twitch hat ihn 2026 mit der GIF-Auswahl im Chat eingefuehrt.
+ *
+ * Aufbau, am echten Chat abgelesen:
+ *
+ *   gifs=0-22|Pnd7qLFuGCOntZcNKB|https://media0.giphy.com/media/.../giphy.gif?cid=...
+ *        ^^^^ ^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *        Bereich  Giphy-ID       Adresse des Bildes
+ *
+ * Der Bereich zeigt wie bei `emotes` auf Zeichen im Nachrichtentext - dort
+ * steht ein Platzhalter wie `[Idk GIF by Respective]`, der ersetzt gehoert.
+ * Wer den Tag nicht auswertet, zeigt genau diesen Platzhalter an.
+ *
+ * Ob mehrere GIFs je Nachricht moeglich sind, ist offen: der Trenner koennte
+ * dafuer nicht `/` sein wie bei Emotes, weil eine URL selbst Schraegstriche
+ * enthaelt. Beobachtet wurde bisher genau eines, und danach ist das hier
+ * gebaut - mehr wuerde ignoriert statt falsch dargestellt.
+ */
+export function parseGifs(tag: string | undefined): ChatMessage['gifs'] {
+  if (!tag) return [];
+  const teile = tag.split('|');
+  if (teile.length < 3) return [];
+
+  // Streng auf Ziffern pruefen und nicht auf `Number` vertrauen: `-1-4`
+  // zerfaellt beim Trennen in ['', '1', '4'], und `Number('')` ist 0. Der
+  // Bereich saehe dann gueltig aus und wuerde den falschen Textteil ersetzen.
+  const bereich = /^(\d+)-(\d+)$/.exec(teile[0] ?? '');
+  if (!bereich) return [];
+  const from = Number(bereich[1]);
+  const to = Number(bereich[2]);
+  const id = teile[1] ?? '';
+  // Alles ab dem zweiten Strich ist die Adresse - falls dort je einer auftaucht.
+  const url = teile.slice(2).join('|');
+
+  if (to < from) return [];
+  // Nur https. Der Tag kommt von Twitch und nicht vom Chatter, aber er landet
+  // als Bildadresse im Stream - das ist kein Ort fuer Vertrauensvorschuss.
+  if (!url.startsWith('https://')) return [];
+
+  return [{ id, url, from, to }];
+}
+
 function parseEmotes(tag: string | undefined, text: string): ChatMessage['emotes'] {
   if (!tag) return [];
   const out: ChatMessage['emotes'] = [];
@@ -84,6 +126,7 @@ export function toChatMessage(m: IrcMessage): ChatMessage | null {
     displayName: m.tags['display-name'] || login,
     text,
     emotes: parseEmotes(m.tags['emotes'], text),
+    gifs: parseGifs(m.tags['gifs']),
     isFirst: m.tags['first-msg'] === '1',
     isReturning: m.tags['returning-chatter'] === '1',
     isCommand: text.startsWith('!'),
@@ -95,10 +138,90 @@ export function toChatMessage(m: IrcMessage): ChatMessage | null {
   };
 }
 
+/**
+ * Ein USERNOTICE ist alles, was Twitch als Ereignis in den Chat schreibt:
+ * Abos, verschenkte Abos, Raids, Ankuendigungen.
+ *
+ * Warum hier und nicht ueber EventSub: es kommt ohnehin ueber dieselbe
+ * Verbindung, kostet keinen zusaetzlichen Token und keine zweite
+ * Wiederverbindung. Was IRC NICHT liefert, sind Follows - dafuer braucht es
+ * EventSub, und bis dahin bleibt das Overlay bei Follows stumm.
+ */
+export type UserNoticeKind =
+  | 'sub' | 'resub' | 'subgift' | 'massgift' | 'raid' | 'announcement' | 'other';
+
+export type UserNotice = {
+  kind: UserNoticeKind;
+  /** Roher msg-id-Wert, falls Twitch etwas Neues schickt. */
+  rawKind: string;
+  ts: string;
+  login: string;
+  displayName: string;
+  /** Twitchs eigener Satz dazu, schon fertig formuliert. */
+  systemMessage: string;
+  /** Was die Person selbst dazugeschrieben hat. Oft leer. */
+  text: string;
+  months?: number;
+  /** Prime, 1000, 2000, 3000 - so wie Twitch es nennt. */
+  tier?: string;
+  /** Beschenkte Person bei subgift. */
+  recipient?: string;
+  /** Anzahl: verschenkte Abos oder mitgebrachte Zuschauer beim Raid. */
+  count?: number;
+};
+
+const NOTICE_KINDS: Record<string, UserNoticeKind> = {
+  sub: 'sub',
+  resub: 'resub',
+  subgift: 'subgift',
+  submysterygift: 'massgift',
+  raid: 'raid',
+  announcement: 'announcement',
+};
+
+function num(v: string | undefined): number | undefined {
+  const n = Number(v);
+  return v !== undefined && v !== '' && Number.isFinite(n) ? n : undefined;
+}
+
+export function toUserNotice(m: IrcMessage): UserNotice | null {
+  if (m.command !== 'USERNOTICE') return null;
+  const rawKind = m.tags['msg-id'] ?? '';
+  const login = m.tags['login'] ?? '';
+  const months = num(m.tags['msg-param-cumulative-months']) ?? num(m.tags['msg-param-months']);
+  // Beim Raid steht die Zuschauerzahl drin, beim Massengeschenk die Anzahl.
+  const count = num(m.tags['msg-param-viewerCount']) ?? num(m.tags['msg-param-mass-gift-count']);
+  const recipient = m.tags['msg-param-recipient-display-name'] ||
+    m.tags['msg-param-recipient-user-name'];
+  const tier = m.tags['msg-param-sub-plan'];
+
+  return {
+    kind: NOTICE_KINDS[rawKind] ?? 'other',
+    rawKind,
+    ts: new Date(Number(m.tags['tmi-sent-ts'] ?? Date.now())).toISOString(),
+    login,
+    displayName: m.tags['display-name'] || login,
+    systemMessage: m.tags['system-msg'] ?? '',
+    text: m.params[1] ?? '',
+    ...(months !== undefined ? { months } : {}),
+    ...(tier ? { tier } : {}),
+    ...(recipient ? { recipient } : {}),
+    ...(count !== undefined ? { count } : {}),
+  };
+}
+
 export type IrcHandlers = {
   onMessage: (msg: ChatMessage) => void;
   onNotice?: (text: string) => void;
   onConnected?: (anonymous: boolean) => void;
+  /** Abos, Raids, Ankuendigungen. */
+  onUserNotice?: (notice: UserNotice) => void;
+  /**
+   * Eine Nachricht oder ein ganzer Chatter wurde geloescht. Das Overlay muss
+   * das mitbekommen, sonst steht eine geloeschte Beleidigung noch eine Minute
+   * lang im Bild - und zwar in der Aufzeichnung.
+   */
+  onClear?: (what: { userId?: string; messageId?: string }) => void;
 };
 
 export type IrcClient = {
@@ -189,6 +312,22 @@ function connectOnce(
           continue;
         }
         if (m.command === 'NOTICE') { handlers.onNotice?.(m.params[1] ?? ''); continue; }
+        if (m.command === 'USERNOTICE') {
+          const notice = toUserNotice(m);
+          if (notice) handlers.onUserNotice?.(notice);
+          continue;
+        }
+        if (m.command === 'CLEARCHAT') {
+          // Ohne target-user-id wurde der ganze Chat geleert.
+          const userId = m.tags['target-user-id'];
+          handlers.onClear?.(userId ? { userId } : {});
+          continue;
+        }
+        if (m.command === 'CLEARMSG') {
+          const messageId = m.tags['target-msg-id'];
+          if (messageId) handlers.onClear?.({ messageId });
+          continue;
+        }
         if (m.command === 'PRIVMSG') {
           const msg = toChatMessage(m);
           if (msg) handlers.onMessage(msg);