@crievo/omni 0.0.0-stage → 0.1.1

package/studio/web/lib/orb.ts

@@ -0,0 +1,270 @@
+/* The voice avatars' renderer. Every avatar on the page is a 2D <canvas>; they all share ONE WebGL
+   context (a page shows more than fifteen at once, and browsers cap the contexts), drawn by the same
+   painter the video scenes use (templates/components/voiceavatar). Each frame an avatar gets its
+   orb drawn into the shared canvas and copied into its own.
+
+   Idle avatars flow at 30 fps, the ones reacting to a voice at 60, the ones off screen not at all.
+   With reduced motion, or `still`, an avatar is drawn once. Without WebGL2 it is a flat gradient. */
+
+import { orbPalette, randomSeed, seedOf } from "./avatars";
+import voiceAvatar from "../../../templates/components/voiceavatar/voiceavatar.js";
+
+/* low, mid, high and all-spectrum levels of the voice, each 0..1 (what voice-envelope.mjs measures) */
+export type Levels = { low: number; mid: number; high: number; all: number };
+
+type Painter = {
+  texture(palette: string[], seed: number): WebGLTexture;
+  deleteTexture(texture: WebGLTexture): void;
+  draw(o: {
+    texture: WebGLTexture;
+    time: number;
+    audio: number[];
+    cum: number[];
+    width: number;
+    height: number;
+    fill?: boolean;
+  }): void;
+};
+/* the video scenes' orb component (templates/components/voiceavatar), as a module */
+const core = voiceAvatar as unknown as {
+  createPainter(gl: WebGL2RenderingContext): Painter;
+  config: { timeScale: number; avgLerp: number; cumLerp: number; overallSound: number };
+};
+
+type Orb = {
+  canvas: HTMLCanvasElement;
+  ctx: CanvasRenderingContext2D;
+  seed: string;
+  fill: boolean;
+  still: boolean;
+  phase: number /* seconds: each voice flows from a different point */;
+  raw: number[] /* low, mid, high, all as last set */;
+  avg: number[];
+  cum: number[];
+  reactiveUntil: number;
+  lastDraw: number;
+  visible: boolean;
+  w: number;
+  h: number;
+  texture: WebGLTexture | null;
+};
+
+const MAX_SIDE = 640;
+const IDLE_MS = 1000 / 30;
+const REACT_MS = 1000 / 60;
+const orbs = new Map<HTMLCanvasElement, Orb>();
+const textures = new Map<string, { texture: WebGLTexture; refs: number }>();
+let glCanvas: HTMLCanvasElement | null = null;
+let painter: Painter | null = null;
+let broken = false;
+let raf = 0;
+
+const reducedMotion = () => window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+
+function ensurePainter(): Painter | null {
+  if (painter || broken) return painter;
+  try {
+    glCanvas = document.createElement("canvas");
+    glCanvas.width = glCanvas.height = 128;
+    const gl = glCanvas.getContext("webgl2", { alpha: true, premultipliedAlpha: true, antialias: false });
+    if (!gl) throw new Error("WebGL2 indisponível");
+    glCanvas.addEventListener("webglcontextlost", e => {
+      e.preventDefault();
+      painter = null;
+      textures.clear();
+      orbs.forEach(o => {
+        o.texture = null;
+      });
+    });
+    glCanvas.addEventListener("webglcontextrestored", () => {
+      ensurePainter();
+      orbs.forEach(o => {
+        acquireTexture(o);
+        drawOrb(o, performance.now());
+      });
+      kick();
+    });
+    painter = core.createPainter(gl);
+  } catch {
+    broken = true;
+    painter = null;
+  }
+  return painter;
+}
+
+function acquireTexture(o: Orb) {
+  const p = ensurePainter();
+  if (!p) return;
+  let entry = textures.get(o.seed);
+  if (!entry) {
+    entry = { texture: p.texture(orbPalette(o.seed), seedOf(o.seed)), refs: 0 };
+    textures.set(o.seed, entry);
+  }
+  entry.refs++;
+  o.texture = entry.texture;
+}
+
+function releaseTexture(o: Orb) {
+  const entry = textures.get(o.seed);
+  if (!entry || !o.texture) return;
+  if (--entry.refs <= 0) {
+    painter?.deleteTexture(entry.texture);
+    textures.delete(o.seed);
+  }
+  o.texture = null;
+}
+
+function drawFlat(o: Orb) {
+  const { ctx, w, h } = o;
+  const [a, b] = orbPalette(o.seed);
+  const g = ctx.createLinearGradient(0, 0, w, h);
+  g.addColorStop(0, a);
+  g.addColorStop(1, b);
+  ctx.clearRect(0, 0, w, h);
+  ctx.fillStyle = g;
+  if (o.fill) ctx.fillRect(0, 0, w, h);
+  else {
+    ctx.beginPath();
+    ctx.arc(w / 2, h / 2, Math.min(w, h) / 2, 0, Math.PI * 2);
+    ctx.fill();
+  }
+}
+
+function drawOrb(o: Orb, now: number) {
+  if (!o.w || !o.h) return;
+  const p = ensurePainter();
+  if (!p || !glCanvas || !o.texture) {
+    drawFlat(o);
+    return;
+  }
+  if (glCanvas.width < o.w || glCanvas.height < o.h) {
+    glCanvas.width = Math.max(glCanvas.width, o.w);
+    glCanvas.height = Math.max(glCanvas.height, o.h);
+  }
+  p.draw({
+    texture: o.texture,
+    time: now / 1000 + o.phase,
+    audio: o.avg,
+    cum: o.cum,
+    width: o.w,
+    height: o.h,
+    fill: o.fill,
+  });
+  o.ctx.clearRect(0, 0, o.w, o.h);
+  /* GL's origin is the bottom-left: the viewport we drew into is the BOTTOM o.h rows of the canvas */
+  o.ctx.drawImage(glCanvas, 0, glCanvas.height - o.h, o.w, o.h, 0, 0, o.w, o.h);
+  o.lastDraw = now;
+}
+
+/* the live orb's smoothing, as per-frame lerps (here scaled by the real elapsed frames) */
+function advance(o: Orb, frames: number) {
+  const { avgLerp, cumLerp, timeScale, overallSound } = core.config;
+  const a = 1 - (1 - avgLerp) ** frames;
+  for (let k = 0; k < 4; k++) {
+    const level = o.raw[k] * overallSound; /* how hard the voice drives the orb */
+    o.avg[k] += a * (level - o.avg[k]);
+    o.cum[k] += cumLerp * level * timeScale * frames;
+  }
+}
+
+function step(now: number) {
+  raf = 0;
+  let running = false;
+  orbs.forEach(o => {
+    if (o.still || !o.visible) return;
+    running = true;
+    const every = now < o.reactiveUntil ? REACT_MS : IDLE_MS;
+    if (now - o.lastDraw < every - 1) return;
+    advance(o, Math.min(6, (now - (o.lastDraw || now - 1000 / 60)) / (1000 / 60)));
+    drawOrb(o, now);
+  });
+  if (running) raf = requestAnimationFrame(step);
+}
+
+function kick() {
+  if (!raf && !reducedMotion()) raf = requestAnimationFrame(step);
+}
+
+function measure(o: Orb) {
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+  const w = Math.min(MAX_SIDE, Math.round(o.canvas.clientWidth * dpr));
+  const h = Math.min(MAX_SIDE, Math.round(o.canvas.clientHeight * dpr));
+  if (w === o.w && h === o.h) return;
+  o.w = o.canvas.width = w;
+  o.h = o.canvas.height = h;
+  drawOrb(o, performance.now());
+}
+
+/* Starts drawing an avatar into `canvas` (sized by CSS). Returns the cleanup. */
+export function attachOrb(canvas: HTMLCanvasElement, opts: { seed: string; fill?: boolean; still?: boolean }) {
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return;
+  const rnd = randomSeed(seedOf(`${opts.seed}:phase`));
+  const o: Orb = {
+    canvas,
+    ctx,
+    seed: opts.seed,
+    fill: !!opts.fill,
+    still: !!opts.still || reducedMotion(),
+    phase: rnd() * 600,
+    raw: [0, 0, 0, 0],
+    avg: [0, 0, 0, 0],
+    cum: [0, 0, 0, 0],
+    reactiveUntil: 0,
+    lastDraw: 0,
+    visible: true,
+    w: 0,
+    h: 0,
+    texture: null,
+  };
+  orbs.set(canvas, o);
+  acquireTexture(o);
+  const resize = new ResizeObserver(() => measure(o));
+  resize.observe(canvas);
+  const seen = new IntersectionObserver(entries => {
+    o.visible = entries[entries.length - 1]?.isIntersecting ?? true;
+    if (o.visible) kick();
+  });
+  seen.observe(canvas);
+  measure(o);
+  kick();
+  return () => {
+    resize.disconnect();
+    seen.disconnect();
+    releaseTexture(o);
+    orbs.delete(canvas);
+  };
+}
+
+/* Feeds the voice into an avatar (null = silence). While it is not null, the avatar draws at 60 fps. */
+export function setOrbLevels(canvas: Element, levels: Levels | null) {
+  const o = orbs.get(canvas as HTMLCanvasElement);
+  if (!o) return false;
+  o.raw = levels ? [levels.low, levels.mid, levels.high, levels.all] : [0, 0, 0, 0];
+  if (levels) o.reactiveUntil = performance.now() + 250;
+  return true;
+}
+
+/* Levels of an AnalyserNode, the way voice-envelope.mjs reads a file: low 0-200 Hz, mid 200-2000 Hz,
+   high 2-20 kHz, and the average of the whole spectrum. */
+export function analyserLevels(an: AnalyserNode, bytes: Uint8Array<ArrayBuffer>): Levels {
+  an.getByteFrequencyData(bytes);
+  const hzPerBin = an.context.sampleRate / 2 / bytes.length;
+  const avg = (fromHz: number, toHz: number) => {
+    const from = Math.min(bytes.length - 1, Math.round(fromHz / hzPerBin));
+    const to = Math.min(bytes.length - 1, Math.max(from, Math.round(toHz / hzPerBin)));
+    let sum = 0;
+    for (let i = from; i <= to; i++) sum += bytes[i];
+    return sum / (to - from + 1) / 255;
+  };
+  return { low: avg(0, 200), mid: avg(200, 2000), high: avg(2000, 20000), all: avg(0, 1e9) };
+}
+
+/* How the avatar breathes with a voice, as a CSS scale: "up" grows with the sound wave (the agent
+   speaks), "down" shrinks (the agent listens). `wave` is the smoothed level, 0..1; silence is 1. */
+export const SWELL = 0.05;
+export const SHRINK = 0.1;
+export function breathScale(direction: "up" | "down", wave: number) {
+  const w = Math.max(0, Math.min(1, wave));
+  return 1 + (direction === "up" ? SWELL : -SHRINK) * w;
+}

package/studio/web/lib/pcm-recorder.ts

@@ -0,0 +1,115 @@
+/* One spoken message for Omni's Claude mode: the microphone as PCM16 mono 24 kHz (what the xAI
+   transcription takes raw), stopped by the user or by itself after a pause once speech started.
+   No audio leaves the page until the recording ends. */
+
+import { openMic } from "./mic-device";
+
+const RATE = 24000;
+const CHUNK = 2400; /* 100 ms */
+const WORKLET = `
+class Capture extends AudioWorkletProcessor {
+  constructor() { super(); this.buf = new Float32Array(${CHUNK}); this.n = 0; }
+  process(inputs) {
+    const ch = inputs[0] && inputs[0][0];
+    if (ch) for (let i = 0; i < ch.length; i++) {
+      this.buf[this.n++] = ch[i];
+      if (this.n === this.buf.length) { this.port.postMessage(this.buf.buffer, [this.buf.buffer]); this.buf = new Float32Array(${CHUNK}); this.n = 0; }
+    }
+    return true;
+  }
+}
+registerProcessor("omni-record", Capture);
+`;
+
+/* speech: RMS above SPEAK for 2 chunks; end: below QUIET for `pauseMs` after that */
+const SPEAK = 0.03;
+const QUIET = 0.015;
+
+export class PcmRecorder {
+  readonly analyser: AnalyserNode;
+  private ctx: AudioContext;
+  private stream: MediaStream | null = null;
+  private node: AudioWorkletNode | null = null;
+  private chunks: Int16Array[] = [];
+  private loud = 0;
+  private spoke = false;
+  private quietMs = 0;
+  private done: ((pcm: Int16Array | null) => void) | null = null;
+
+  constructor(private opts: { pauseMs?: number; maxMs?: number } = {}) {
+    this.ctx = new AudioContext({ sampleRate: RATE });
+    this.analyser = this.ctx.createAnalyser();
+    this.analyser.fftSize = 1024;
+  }
+
+  /* resolves with the recording when it ends (null: nothing was said) */
+  async record(): Promise<Int16Array | null> {
+    await this.ctx.resume();
+    this.stream = await openMic();
+    const url = URL.createObjectURL(new Blob([WORKLET], { type: "application/javascript" }));
+    await this.ctx.audioWorklet.addModule(url);
+    URL.revokeObjectURL(url);
+    const source = this.ctx.createMediaStreamSource(this.stream);
+    this.node = new AudioWorkletNode(this.ctx, "omni-record");
+    this.node.port.onmessage = (e: MessageEvent<ArrayBuffer>) => this.onChunk(new Float32Array(e.data));
+    source.connect(this.node);
+    source.connect(this.analyser);
+    return new Promise(resolve => {
+      this.done = resolve;
+    });
+  }
+
+  private onChunk(f: Float32Array) {
+    let sum = 0;
+    const pcm = new Int16Array(f.length);
+    for (let i = 0; i < f.length; i++) {
+      const s = Math.max(-1, Math.min(1, f[i]));
+      sum += s * s;
+      pcm[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+    }
+    this.chunks.push(pcm);
+    const rms = Math.sqrt(sum / f.length);
+    const ms = (f.length / RATE) * 1000;
+    if (rms > SPEAK) {
+      if (++this.loud >= 2) this.spoke = true;
+      this.quietMs = 0;
+    } else {
+      this.loud = 0;
+      if (this.spoke && rms < QUIET) this.quietMs += ms;
+    }
+    const total = this.chunks.length * ms;
+    if ((this.spoke && this.quietMs >= (this.opts.pauseMs ?? 1500)) || total >= (this.opts.maxMs ?? 60_000))
+      this.stop();
+  }
+
+  /* ends the recording now (the user tapped) */
+  stop() {
+    if (!this.done) return;
+    const done = this.done;
+    this.done = null;
+    this.node?.disconnect();
+    this.stream?.getTracks().forEach(t => t.stop());
+    void this.ctx.close();
+    if (!this.spoke) return done(null);
+    const length = this.chunks.reduce((n, c) => n + c.length, 0);
+    const all = new Int16Array(length);
+    let at = 0;
+    for (const c of this.chunks) {
+      all.set(c, at);
+      at += c.length;
+    }
+    done(all);
+  }
+
+  cancel() {
+    this.spoke = false;
+    this.stop();
+  }
+}
+
+export function pcmToBase64(pcm: Int16Array): string {
+  const bytes = new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(s);
+}

package/studio/web/lib/platforms.ts

@@ -0,0 +1,17 @@
+/* The publishing platforms (YouTube, Instagram, TikTok). */
+
+export type PlatformId = "youtube" | "instagram" | "tiktok";
+
+export const PLATFORMS: { id: PlatformId; name: string }[] = [
+  { id: "youtube", name: "YouTube" },
+  { id: "instagram", name: "Instagram" },
+  { id: "tiktok", name: "TikTok" },
+];
+
+export const platformName = (id: string) => PLATFORMS.find(p => p.id === id)?.name ?? id;
+
+/* "no YouTube, no Instagram e no TikTok" */
+export const formatPlatformList = (ids: string[]) => {
+  const names = ids.map(id => `no ${platformName(id)}`);
+  return names.length <= 1 ? names.join("") : `${names.slice(0, -1).join(", ")} e ${names.at(-1)}`;
+};

package/studio/web/lib/providers.ts

@@ -0,0 +1,27 @@
+/* The voice providers: ids, display names, where to open an account, and whether a key is set. */
+
+import type { Settings, VoiceProfile } from "../types/api";
+
+export type VoiceProviderId = "fish" | "cartesia" | "voicestudio" | "elevenlabs";
+export const ALL_VOICE_PROVIDERS: VoiceProviderId[] = ["elevenlabs", "fish", "cartesia", "voicestudio"];
+
+export const PROVIDER_NAME: Record<string, string> = {
+  elevenlabs: "ElevenLabs",
+  fish: "Fish Audio",
+  cartesia: "Cartesia",
+  voicestudio: "VoiceStudio",
+};
+
+/* where to create each provider's account; the key goes in Configurações → Voz */
+export const PROVIDER_ACCOUNT_URL: Record<string, string> = {
+  fish: "https://fish.audio",
+  cartesia: "https://play.cartesia.ai",
+  elevenlabs: "https://elevenlabs.io",
+};
+
+/* VoiceStudio is local: no key */
+export const hasProviderKey = (settings: Settings, p: VoiceProviderId) =>
+  p === "voicestudio" ? true : !!(settings.voice[p].key.masked || settings.voice[p].key.in_env);
+
+/* a voice profile's providers, in try order, by display name */
+export const providerNamesOf = (p: VoiceProfile) => p.order.map(id => PROVIDER_NAME[id] ?? id);

package/studio/web/lib/publish-draft.ts

@@ -0,0 +1,52 @@
+/* What the Publish stage had on screen when "Agendar" went to the Schedule: text, platforms,
+   privacy and the chosen day. Kept in this tab's sessionStorage, one per video, and back to the
+   Publish stage once the day and time are picked in the Schedule.
+   `picking`: the Schedule is waiting for this video's day. */
+
+export type PublishDraft = {
+  slug: string;
+  title: string;
+  text: { title: string; description: string; caption: string };
+  checked: Record<string, boolean>;
+  /* platforms freed to publish again ("Republicar") */
+  released?: Record<string, boolean>;
+  privacy: string | null;
+  privacyTiktok: string | null;
+  /* YYYY-MM-DDTHH:mm, this Mac's time */
+  when: string | null;
+  picking: boolean;
+};
+
+const STORAGE_KEY = "omnivideo.publish-draft";
+
+function all(): Record<string, PublishDraft> {
+  try {
+    return JSON.parse(sessionStorage.getItem(STORAGE_KEY) ?? "{}") ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function saveAll(r: Record<string, PublishDraft>) {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(r));
+  } catch {
+    /* no storage: the draft lives only on screen */
+  }
+}
+
+export const readPublishDraft = (slug: string): PublishDraft | null => all()[slug] ?? null;
+
+/* the video whose day the Schedule is waiting for (the most recent, if more than one) */
+export const pickingPublishDraft = (): PublishDraft | null => Object.values(all()).find(r => r.picking) ?? null;
+
+export function savePublishDraft(r: PublishDraft) {
+  /* only one video picks a day at a time */
+  const rest = Object.fromEntries(Object.entries(all()).map(([k, x]) => [k, r.picking ? { ...x, picking: false } : x]));
+  saveAll({ ...rest, [r.slug]: r });
+}
+
+export function deletePublishDraft(slug: string) {
+  const { [slug]: _, ...rest } = all();
+  saveAll(rest);
+}

package/studio/web/lib/publish-settings.ts

@@ -0,0 +1,81 @@
+/* Pure pieces of Configurações → Publicação (pages/SettingsPage/components/PublishingCategory):
+   the option lists, the text ↔ value conversions of the form fields and the outcome of a
+   browser login. */
+
+import type { ActionResult } from "./api";
+
+/* --- YouTube ---------------------------------------------------------------------- */
+export const YT_CATEGORIES: [string, string][] = [
+  ["1", "Cinema e animação"],
+  ["2", "Automóveis"],
+  ["10", "Música"],
+  ["15", "Animais"],
+  ["17", "Esportes"],
+  ["19", "Viagens"],
+  ["20", "Games"],
+  ["22", "Pessoas e blogs"],
+  ["23", "Comédia"],
+  ["24", "Entretenimento"],
+  ["25", "Notícias e política"],
+  ["26", "Como fazer e estilo"],
+  ["27", "Educação"],
+  ["28", "Ciência e tecnologia"],
+];
+export const PRIVACY_OPTIONS: [string, string][] = [
+  ["private", "Privado"],
+  ["unlisted", "Não listado"],
+  ["public", "Público"],
+];
+
+/* the category picker's options: an id outside the list stays as the first option */
+export const youtubeCategoryOptions = (current: string) => [
+  ...(YT_CATEGORIES.some(([k]) => k === current) ? [] : [{ value: current, label: current }]),
+  ...YT_CATEGORIES.map(([k, name]) => ({ value: k, label: name })),
+];
+
+/* --- TikTok ---------------------------------------------------------------------- */
+export const TIKTOK_PRIVACY_OPTIONS: [string, string][] = [
+  ["SELF_ONLY", "Só eu"],
+  ["MUTUAL_FOLLOW_FRIENDS", "Amigos"],
+  ["FOLLOWER_OF_CREATOR", "Seguidores"],
+  ["PUBLIC_TO_EVERYONE", "Todo mundo"],
+];
+
+/* --- schedule ---------------------------------------------------------------------- */
+export const STATE_LABEL: Record<string, string> = {
+  scheduled: "Agendado",
+  publishing: "Publicando",
+  failed: "Falhou",
+  missed: "Passou da hora",
+};
+
+/* --- field conversions ------------------------------------------------------------- */
+/* the cover becomes text on screen and goes back to a number (or null) on save */
+export const coverToText = (v: number | null) => (v == null ? "" : String(v));
+export const coverToNumber = (v: string) => (v.trim() === "" ? null : v.trim().replace(",", "."));
+
+/* the hashtags as one line on screen, back to a list on save */
+export const hashtagsToText = (hashtags: string[]) => hashtags.map(h => `#${h}`).join(" ");
+export const hashtagsToList = (text: string) => text.split(/[\s,]+/).filter(Boolean);
+
+/* a number field typed with a comma or a dot */
+export const decimalOf = (value: string) => Number(value.replace(",", "."));
+
+/* a platform checked or unchecked in a list, without repeats */
+export const togglePlatform = (platforms: string[], id: string, yes: boolean) =>
+  yes ? [...new Set([...platforms, id])] : platforms.filter(x => x !== id);
+
+/* --- browser login (YouTube and TikTok) ---------------------------------------------- */
+export type Connection = { state: "waiting" | "ok" | "error"; url: string | null; output: string; at: number } | null;
+
+/* a finished login's message: the output's last line that isn't the link */
+export function connectionResult(c: NonNullable<Connection>): ActionResult {
+  const last =
+    c.output
+      .split("\n")
+      .filter(l => !l.startsWith("url: "))
+      .pop() ?? "";
+  return c.state === "ok"
+    ? { ok: true, output: last || "conectado" }
+    : { ok: false, error: last || "O login não terminou" };
+}

package/studio/web/lib/query-client.ts

@@ -0,0 +1,122 @@
+/* The TanStack Query client and the bridge from the SSE stream to its cache.
+   Pushed resources (queue, services, sessions) are written with setQueryData; "changed"
+   notices (video, reference, omnichat, analytics) invalidate their keys, debounced 150 ms
+   so a burst of file writes refetches once. Data never goes stale on its own: the stream
+   is what refreshes it. */
+
+import { QueryClient, type QueryKey } from "@tanstack/react-query";
+import { onReconnect, subscribe } from "./sse";
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: Infinity,
+      gcTime: 5 * 60_000,
+      retry: false,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+    },
+  },
+});
+
+/* query keys (GLOSSARY §10.1); hooks and invalidations use only these */
+export const queryKeys = {
+  videos: ["videos"] as const,
+  video: (slug: string) => ["video", slug] as const,
+  queue: ["queue"] as const,
+  services: ["services"] as const,
+  sessions: ["sessions"] as const,
+  session: (id: string) => ["session", id] as const,
+  references: ["references"] as const,
+  reference: (name: string) => ["reference", name] as const,
+  /* rules = false: GET /api/omnichat?rules=0 */
+  omnichat: (rules = true) => ["omnichat", rules ? "rules" : "no-rules"] as const,
+  omnichatRule: (apiBase: string) => ["omnichat-rule", apiBase] as const,
+  analytics: ["analytics"] as const,
+  reel: (slug: string) => ["reel", slug] as const,
+  settings: ["settings"] as const,
+  usage: ["usage"] as const,
+  accounts: ["accounts"] as const,
+  schedule: ["schedule"] as const,
+  onboarding: ["onboarding"] as const,
+  agent: ["agent"] as const,
+  admin: ["admin"] as const,
+  agentConversations: ["agent-conversations"] as const,
+  runner: ["runner"] as const,
+};
+
+/* the omnichat rule API of a video, of a content's carousel or of an outside post */
+export const videoOmnichatApi = (slug: string) => `/api/videos/${encodeURIComponent(slug)}/omnichat`;
+export const carouselOmnichatApi = (slug: string) => `/api/videos/${encodeURIComponent(slug)}/carousel/omnichat`;
+export const postOmnichatApi = (code: string) => `/api/omnichat/posts/${encodeURIComponent(code)}`;
+
+const timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+/* invalidate (prefix match) after 150 ms of quiet for that key */
+export function invalidateSoon(key: QueryKey) {
+  const id = JSON.stringify(key);
+  clearTimeout(timers.get(id));
+  timers.set(
+    id,
+    setTimeout(() => {
+      timers.delete(id);
+      queryClient.invalidateQueries({ queryKey: key });
+    }, 150),
+  );
+}
+
+/* invalidate now, e.g. after a POST that changed the data */
+export function invalidate(...keys: QueryKey[]) {
+  return Promise.all(keys.map(queryKey => queryClient.invalidateQueries({ queryKey })));
+}
+
+let bridged = false;
+
+/* wire the SSE stream into the cache; called once by main.tsx */
+export function connectSseToQueries() {
+  if (bridged) return;
+  bridged = true;
+  onReconnect(() => void queryClient.invalidateQueries());
+  subscribe((event, data) => {
+    switch (event) {
+      case "queue":
+        queryClient.setQueryData(queryKeys.queue, data);
+        break;
+      case "services":
+        queryClient.setQueryData(queryKeys.services, data);
+        break;
+      case "sessions":
+        queryClient.setQueryData(queryKeys.sessions, data);
+        invalidateSoon(["session"]);
+        break;
+      case "video":
+        invalidateSoon(queryKeys.videos);
+        invalidateSoon(queryKeys.schedule);
+        if (data?.slug) invalidateSoon(queryKeys.video(data.slug));
+        break;
+      case "reference":
+        invalidateSoon(queryKeys.references);
+        if (data?.name) invalidateSoon(queryKeys.reference(data.name));
+        break;
+      case "omnichat":
+        /* { slug } a video's (or its carousel's) rule/record/publication changed, { code } an outside post's, {} the account pause */
+        invalidateSoon(["omnichat"]);
+        if (data?.slug) {
+          invalidateSoon(queryKeys.omnichatRule(videoOmnichatApi(data.slug)));
+          invalidateSoon(queryKeys.omnichatRule(carouselOmnichatApi(data.slug)));
+        }
+        if (data?.code) invalidateSoon(queryKeys.omnichatRule(postOmnichatApi(data.code)));
+        break;
+      case "agent":
+        /* the admin changed Omni (admin panel): on, engine, voice, models */
+        invalidateSoon(queryKeys.agent);
+        invalidateSoon(queryKeys.admin);
+        break;
+      case "analytics":
+        /* metrics, a Reel's analysis, the account snapshot or channel/ (playbook and analyses) */
+        invalidateSoon(queryKeys.analytics);
+        invalidateSoon(["reel"]);
+        break;
+    }
+  });
+}