@crievo/omni 0.0.0-stage → 0.1.0

package/studio/web/hooks/useOmniDock.ts

@@ -0,0 +1,142 @@
+/* Where Omni's panel sits: it opens from the sidebar button and lives in one of the window's four corners.
+   Its top bar drags it; on release it snaps to the nearest corner, remembered in localStorage. It never
+   covers the sidebar: the left corners sit against the sidebar's edge and follow it when the menu is
+   collapsed or expanded (the right ones do not move). Never dragged, it is at the bottom left. */
+
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type PointerEvent as ReactPointerEvent,
+} from "react";
+
+type Corner = { h: "left" | "right"; v: "top" | "bottom" };
+/* the sidebar's reach, in window pixels: how far from the left (a side menu) or from the top (a bar) */
+type Inset = { left: number; top: number };
+type Rect = { left: number; top: number; w: number; h: number };
+
+const KEY = "omni.dock.panel";
+const MARGIN = 8;
+const DRAG_PX = 5;
+const HOME: Corner = { h: "left", v: "bottom" };
+
+function load(): Corner {
+  try {
+    const d = JSON.parse(localStorage.getItem(KEY) ?? "null");
+    if ((d?.h === "left" || d?.h === "right") && (d?.v === "top" || d?.v === "bottom")) return { h: d.h, v: d.v };
+  } catch {
+    /* no storage or a broken value: the default place */
+  }
+  return HOME;
+}
+
+/* the menu is a side column on desktop and a bar on top on a narrow screen */
+function measureInset(): Inset {
+  const menu = document.querySelector(".menu")?.getBoundingClientRect();
+  if (!menu) return { left: 0, top: 0 };
+  return menu.width < innerWidth / 2 ? { left: menu.right, top: 0 } : { left: 0, top: Math.max(0, menu.bottom) };
+}
+
+const clamp = (n: number, lo: number, hi: number) => Math.min(Math.max(n, lo), Math.max(lo, hi));
+
+/* the nearest corner of the free area (the window minus the sidebar) to the card's center */
+function nearest(r: Rect, inset: Inset): Corner {
+  const cx = r.left + r.w / 2;
+  const cy = r.top + r.h / 2;
+  return {
+    h: cx < (inset.left + innerWidth) / 2 ? "left" : "right",
+    v: cy < (inset.top + innerHeight) / 2 ? "top" : "bottom",
+  };
+}
+
+export function useOmniDock(open: boolean) {
+  const [saved, setSaved] = useState<Corner>(load);
+  /* while dragging, the card follows the pointer (window pixels) and the corner is only saved on release */
+  const [live, setLive] = useState<{ left: number; top: number } | null>(null);
+  const [inset, setInset] = useState<Inset>({ left: 0, top: 0 });
+  const [dragging, setDragging] = useState(false);
+  const latest = useRef({ live, inset, saved });
+  latest.current = { live, inset, saved };
+
+  /* the menu changes width when collapsed or expanded: follow it, the card slides with the CSS transition */
+  useEffect(() => {
+    const read = () =>
+      setInset(prev => {
+        const next = measureInset();
+        return prev.left === next.left && prev.top === next.top ? prev : next;
+      });
+    read();
+    addEventListener("resize", read);
+    const menu = document.querySelector(".menu");
+    const ro = menu && new ResizeObserver(read);
+    if (menu) ro?.observe(menu);
+    return () => {
+      removeEventListener("resize", read);
+      ro?.disconnect();
+    };
+  }, [open]);
+
+  /* the pointer went down on the panel's top bar (its own buttons are not handles) */
+  const start = useCallback((e: ReactPointerEvent) => {
+    if (e.button !== 0 || (e.pointerType === "mouse" && e.buttons !== 1)) return;
+    if ((e.target as HTMLElement).closest("button, a, input, textarea, select, [role=radio], [role=slider]")) return;
+    const card = (e.currentTarget as HTMLElement).closest(".omni-dock")?.getBoundingClientRect();
+    if (!card) return;
+    const from = { x: e.clientX, y: e.clientY, left: card.left, top: card.top, w: card.width, h: card.height };
+    let moved = false;
+    const move = (m: PointerEvent) => {
+      const dx = m.clientX - from.x;
+      const dy = m.clientY - from.y;
+      if (!moved && Math.hypot(dx, dy) < DRAG_PX) return;
+      if (!moved) {
+        moved = true;
+        setDragging(true);
+      }
+      const { inset } = latest.current;
+      /* never over the sidebar, not even while dragging */
+      setLive({
+        left: clamp(from.left + dx, inset.left + MARGIN, innerWidth - from.w - MARGIN),
+        top: clamp(from.top + dy, inset.top + MARGIN, innerHeight - from.h - MARGIN),
+      });
+    };
+    const end = () => {
+      removeEventListener("pointermove", move);
+      removeEventListener("pointerup", end);
+      removeEventListener("pointercancel", end);
+      if (!moved) return;
+      setDragging(false);
+      const { live, inset, saved } = latest.current;
+      const next = live ? nearest({ ...live, w: from.w, h: from.h }, inset) : saved;
+      setLive(null);
+      setSaved(next);
+      try {
+        localStorage.setItem(KEY, JSON.stringify(next));
+      } catch {
+        /* the position just is not remembered */
+      }
+    };
+    addEventListener("pointermove", move);
+    addEventListener("pointerup", end);
+    addEventListener("pointercancel", end);
+  }, []);
+
+  const left = inset.left + MARGIN;
+  const top = inset.top + MARGIN;
+  const cardStyle = (open && {
+    ...(live
+      ? { left: live.left, top: live.top, right: "auto", bottom: "auto" }
+      : {
+          left: saved.h === "left" ? left : "auto",
+          right: saved.h === "right" ? MARGIN : "auto",
+          top: saved.v === "top" ? top : "auto",
+          bottom: saved.v === "bottom" ? MARGIN : "auto",
+        }),
+    /* the card's room: what is left beside the sidebar, for the width and height in the CSS */
+    ["--omni-px" as string]: `${left}px`,
+    ["--omni-py" as string]: `${top}px`,
+  }) as CSSProperties | undefined;
+
+  return { dragging, start, cardStyle };
+}

package/studio/web/hooks/useOmniGreeting.ts

@@ -0,0 +1,60 @@
+/* Omni's greeting when the panel opens: the saved voice sample (GET /api/agent/voices/:gender/sample,
+   cached in .agent/samples), so it costs nothing on xAI after the first time. The same player says the
+   recorded "no que posso ajudar?" (clip "prompt") when a call starts and the user stays quiet. The sound
+   goes through an analyser so the avatar follows it, like it does in a live conversation. */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { AgentGender } from "../types/api";
+
+export type GreetingClip = "greeting" | "prompt";
+
+export function useOmniGreeting() {
+  const [playing, setPlaying] = useState(false);
+  const analyser = useRef<AnalyserNode | null>(null);
+  const audio = useRef<HTMLAudioElement | null>(null);
+  const ctx = useRef<AudioContext | null>(null);
+
+  const stop = useCallback(() => {
+    audio.current?.pause();
+    audio.current = null;
+    setPlaying(false);
+  }, []);
+
+  const play = useCallback(
+    (gender: AgentGender, clip: GreetingClip = "greeting") => {
+      stop();
+      const a = new Audio(`/api/agent/voices/${gender}/sample${clip === "prompt" ? "?clip=prompt" : ""}`);
+      audio.current = a;
+      try {
+        ctx.current ??= new AudioContext();
+        void ctx.current.resume();
+        const an = ctx.current.createAnalyser();
+        an.fftSize = 512;
+        ctx.current.createMediaElementSource(a).connect(an);
+        an.connect(ctx.current.destination);
+        analyser.current = an;
+      } catch {
+        analyser.current = null;
+      }
+      const done = () => {
+        if (audio.current === a) stop();
+      };
+      a.onended = done;
+      a.onerror = done;
+      setPlaying(true);
+      /* the browser may refuse autoplay: then it is simply silent */
+      a.play().catch(done);
+    },
+    [stop],
+  );
+
+  useEffect(
+    () => () => {
+      audio.current?.pause();
+      void ctx.current?.close();
+    },
+    [],
+  );
+
+  return { playing, analyser, play, stop };
+}

package/studio/web/hooks/useOmniHotword.ts

@@ -0,0 +1,128 @@
+/* "Oi, Omni" (lib/omni-hotword.ts) in the app shell: the switch (per browser, the same in every tab),
+   and the listener, which runs in one studio tab only (a Web Lock: when that tab closes, another takes
+   over) and stops while Omni is busy in any tab (a call, the greeting, a Claude-mode recording), so the
+   microphone is free for the conversation and a second call never opens. */
+
+import { useEffect, useRef, useState } from "react";
+import {
+  HOTWORD_STORAGE_KEY,
+  HotwordListener,
+  type HotwordState,
+  loadHotwordOn,
+  saveHotwordOn,
+} from "../lib/omni-hotword";
+
+export type HotwordStatus = HotwordState | "off" | "paused" | "elsewhere";
+
+const LOCK = "omni-hotword";
+const CHANNEL = "omni-hotword";
+/* a busy tab says so this often; one silent for STALE_MS (closed mid-call) no longer counts */
+const BEAT_MS = 5000;
+const STALE_MS = 12_000;
+
+export function useOmniHotword({
+  available,
+  busy,
+  onCall,
+}: {
+  /* Omni is on and reachable */
+  available: boolean;
+  /* this tab's Omni is talking or recording */
+  busy: boolean;
+  onCall: () => void;
+}) {
+  const [on, setOnState] = useState(loadHotwordOn);
+  useEffect(() => {
+    const sync = (e: StorageEvent) => {
+      if (e.key === HOTWORD_STORAGE_KEY) setOnState(loadHotwordOn());
+    };
+    window.addEventListener("storage", sync);
+    return () => window.removeEventListener("storage", sync);
+  }, []);
+  const setOn = (v: boolean) => {
+    saveHotwordOn(v);
+    setOnState(v);
+  };
+  const wanted = on && available;
+
+  /* the tab that listens */
+  const [leader, setLeader] = useState(false);
+  useEffect(() => {
+    if (!wanted) return setLeader(false);
+    if (!navigator.locks) return setLeader(true);
+    const abort = new AbortController();
+    let release: (() => void) | null = null;
+    navigator.locks
+      .request(LOCK, { signal: abort.signal }, () => {
+        setLeader(true);
+        return new Promise<void>(r => {
+          release = r;
+        });
+      })
+      .catch(() => {});
+    return () => {
+      abort.abort();
+      release?.();
+      setLeader(false);
+    };
+  }, [wanted]);
+
+  /* the other tabs' calls */
+  const [othersBusy, setOthersBusy] = useState(false);
+  const me = useRef(Math.random().toString(36).slice(2));
+  const busyRef = useRef(busy);
+  busyRef.current = busy;
+  const channel = useRef<BroadcastChannel | null>(null);
+  useEffect(() => {
+    if (typeof BroadcastChannel === "undefined") return;
+    const ch = new BroadcastChannel(CHANNEL);
+    channel.current = ch;
+    const seen = new Map<string, number>();
+    const recount = () => {
+      const now = Date.now();
+      for (const [id, at] of seen) if (now - at > STALE_MS) seen.delete(id);
+      setOthersBusy(seen.size > 0);
+    };
+    ch.onmessage = (e: MessageEvent<{ id: string; busy: boolean }>) => {
+      if (e.data.busy) seen.set(e.data.id, Date.now());
+      else seen.delete(e.data.id);
+      recount();
+    };
+    const beat = setInterval(() => {
+      if (busyRef.current) ch.postMessage({ id: me.current, busy: true });
+      recount();
+    }, BEAT_MS);
+    return () => {
+      clearInterval(beat);
+      ch.postMessage({ id: me.current, busy: false });
+      ch.close();
+      channel.current = null;
+    };
+  }, []);
+  useEffect(() => {
+    channel.current?.postMessage({ id: me.current, busy });
+  }, [busy]);
+
+  const paused = busy || othersBusy;
+  const [state, setState] = useState<HotwordState | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const onCallRef = useRef(onCall);
+  onCallRef.current = onCall;
+  useEffect(() => {
+    setState(null);
+    setError(null);
+    if (!wanted || !leader || paused) return;
+    const listener = new HotwordListener({
+      onCall: () => onCallRef.current(),
+      onState: (s, e) => {
+        setState(s);
+        setError(e ?? null);
+      },
+    });
+    void listener.start();
+    return () => listener.stop();
+  }, [wanted, leader, paused]);
+
+  const status: HotwordStatus = !wanted ? "off" : !leader ? "elsewhere" : paused ? "paused" : (state ?? "starting");
+  return { on, setOn, status, error };
+}

package/studio/web/hooks/useOmnichat.ts

@@ -0,0 +1,26 @@
+/* The SSE "omnichat" notice arrives when the rule, the record or the publication.json of a
+   video ({ slug }) or of an outside post ({ code }) changes, or the account pause ({}). */
+
+import { api } from "../lib/api";
+import { ruleApi, ruleApiBase, type RuleTargetRef } from "../lib/omnichat-api";
+import { queryKeys } from "../lib/query-client";
+import type { OmnichatRuleDetail, OmnichatState } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* rules = false: without the rule list (GET /api/omnichat?rules=0) */
+export function useOmnichatState(rules = true) {
+  const { data, error, reload } = useLiveQuery(queryKeys.omnichat(rules), () =>
+    api.omnichat.$get({ query: rules ? {} : { rules: "0" } }),
+  );
+  const state: OmnichatState | null = data;
+  return { state, error, reload };
+}
+
+/* the rule of a video ({ slug }), of a content's carousel ({ slug, carousel }) or of a post ({ code }) */
+export function useOmnichatRule(target: RuleTargetRef) {
+  const { data, error, reload } = useLiveQuery(queryKeys.omnichatRule(ruleApiBase(target)), () =>
+    ruleApi(target).get(),
+  );
+  const detail: OmnichatRuleDetail | null = data;
+  return { detail, error, reload };
+}

package/studio/web/hooks/useOnboarding.ts

@@ -0,0 +1,27 @@
+/* Getting started (/api/onboarding): the docs/onboarding.md guide in steps, each with the
+   tools/setup.mjs check. `reload(true)` asks for a fresh check (?fresh=1). */
+
+import { useCallback, useState } from "react";
+import { api, errorText, read } from "../lib/api";
+import { queryClient, queryKeys } from "../lib/query-client";
+import type { Onboarding } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+export function useOnboarding() {
+  const { data, error, isFetching } = useLiveQuery(queryKeys.onboarding, () => api.onboarding.$get({ query: {} }));
+  const onboarding: Onboarding | null = data;
+  const [freshError, setFreshError] = useState<string | null>(null);
+  const [checking, setChecking] = useState(false);
+  const reload = useCallback(async (fresh = false) => {
+    setChecking(true);
+    setFreshError(null);
+    try {
+      const next: Onboarding = await read(api.onboarding.$get({ query: fresh ? { fresh: "1" } : {} }));
+      queryClient.setQueryData(queryKeys.onboarding, next);
+    } catch (e) {
+      setFreshError(errorText(e));
+    }
+    setChecking(false);
+  }, []);
+  return { onboarding, error: freshError ?? error, checking: checking || isFetching, reload };
+}

package/studio/web/hooks/usePost.ts

@@ -0,0 +1,23 @@
+/* A POST to the studio API as a TanStack mutation. On ok, the given query keys are
+   invalidated (the SSE stream refreshes most data anyway; this is for what it doesn't push:
+   settings, usage, accounts…). The variable is the typed client call:
+   post.mutateAsync(() => api.usage.refresh.$post({ json: {} })). */
+
+import { useMutation, type QueryKey } from "@tanstack/react-query";
+import type { ClientResponse } from "hono/client";
+import { send, type Envelope } from "../lib/api";
+import { invalidate } from "../lib/query-client";
+
+type AnyResponse = ClientResponse<unknown, number, "json" | "text" | "redirect">;
+
+export function usePost<R extends AnyResponse>(
+  options: { invalidate?: QueryKey[]; onDone?: (r: Envelope<R>) => void } = {},
+) {
+  return useMutation({
+    mutationFn: (request: () => Promise<R>) => send(request()),
+    onSuccess: async r => {
+      if (r.ok && options.invalidate?.length) await invalidate(...options.invalidate);
+      options.onDone?.(r);
+    },
+  });
+}

package/studio/web/hooks/useQueue.ts

@@ -0,0 +1,10 @@
+import { api } from "../lib/api";
+import { queryKeys } from "../lib/query-client";
+import type { Queue } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* the machine queue; the SSE "queue" event pushes it whole */
+export function useQueue(): Queue | null {
+  const queue: Queue | null = useLiveQuery(queryKeys.queue, () => api.queue.$get()).data;
+  return queue;
+}

package/studio/web/hooks/useReferences.ts

@@ -0,0 +1,20 @@
+import { api, enc } from "../lib/api";
+import { queryKeys } from "../lib/query-client";
+import type { ReferenceDetail, ReferenceSummary } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* refetched on every SSE "reference" notice */
+export function useReferences() {
+  const { data, error, reload } = useLiveQuery(queryKeys.references, () => api.references.$get());
+  const references: ReferenceSummary[] | null = data;
+  return { references, error, reload };
+}
+
+/* refetched on the SSE "reference" notice for this name */
+export function useReference(name: string) {
+  const { data, error, reload } = useLiveQuery(queryKeys.reference(name), () =>
+    api.references[":name"].$get({ param: { name: enc(name) } }),
+  );
+  const reference: ReferenceDetail | null = data;
+  return { reference, error, reload };
+}

package/studio/web/hooks/useRuleEditor.ts

@@ -0,0 +1,101 @@
+/* The edit state of one omnichat rule (OmnichatRulePanel): the form against the saved rule,
+   the two-click confirmations (enable, save while enabled), the dry run and the requests. */
+
+import { useEffect, useState } from "react";
+import type { ClientResponse } from "hono/client";
+import { send, type ActionResult } from "../lib/api";
+import { ruleApi } from "../lib/omnichat-api";
+import { ruleBodyOf, ruleFormOf, type RuleForm, type RuleTarget } from "../components/RuleForm";
+import { useOmnichatRule } from "./useOmnichat";
+
+export function useRuleEditor(target: RuleTarget) {
+  const { detail: d, error: readError, reload } = useOmnichatRule(target);
+  const rules = ruleApi(target);
+  const rule = d?.rule ?? null;
+  const initial = ruleFormOf(rule, d);
+  const key = JSON.stringify(initial);
+  /* the form restarts when the saved rule changes, not when the defaults that fill its empty fields
+     change: a new default in the config must not wipe what is being written */
+  const ruleKey = JSON.stringify([!!d, rule, d?.found_link ?? null]);
+  const [form, setForm] = useState<RuleForm>(initial);
+  useEffect(() => {
+    setForm(initial);
+  }, [ruleKey]);
+  const changed = JSON.stringify(form) !== key;
+  const [busy, setBusy] = useState<string | null>(null);
+  const [result, setResult] = useState<ActionResult>(null);
+  const [problems, setProblems] = useState<string[]>([]);
+  const [confirm, setConfirm] = useState(false);
+  /* an enabled rule that changes (another word, any comment) rereads the 7 days with the new rule:
+     saving also goes outside and asks for the second click */
+  const [confirmSave, setConfirmSave] = useState(false);
+  const [dryRun, setDryRun] = useState<string | null>(null);
+
+  /* several fields at once: a choice that sets more than one (the delivery mode) is a single edit */
+  const fields = (patch: Partial<RuleForm>) => {
+    setForm(s => ({ ...s, ...patch }));
+    setConfirm(false);
+    setConfirmSave(false);
+  };
+  const field = <K extends keyof RuleForm>(k: K, v: RuleForm[K]) => fields({ [k]: v });
+  const request = async <R extends ClientResponse<unknown, number, "json" | "text" | "redirect">>(
+    name: string,
+    call: () => Promise<R>,
+  ) => {
+    setBusy(name);
+    setResult(null);
+    const r = await send(call());
+    setBusy(null);
+    setResult(r);
+    if (r.ok) reload();
+    return r;
+  };
+
+  const save = async () => {
+    const r = await request("save", () => rules.save(ruleBodyOf(form)));
+    setConfirmSave(false);
+    if (r.ok) setProblems(r.problems ?? []);
+  };
+  const enable = async (on: boolean) => {
+    const r = await request(on ? "enable" : "disable", () => rules.enable(on));
+    setConfirm(false);
+    if (r.ok) setProblems([]);
+  };
+  const runDry = async () => {
+    setDryRun(null);
+    const r = await request("dry-run", () => rules.dryRun());
+    if (r.ok) {
+      setDryRun(r.output ?? "");
+      setResult(null);
+    }
+  };
+
+  return {
+    d,
+    readError,
+    reload,
+    rules,
+    rule,
+    initial,
+    changed,
+    form,
+    setForm,
+    busy,
+    result,
+    problems,
+    confirm,
+    setConfirm,
+    confirmSave,
+    setConfirmSave,
+    dryRun,
+    setDryRun,
+    field,
+    fields,
+    request,
+    save,
+    enable,
+    runDry,
+  };
+}
+
+export type RuleEditor = ReturnType<typeof useRuleEditor>;

package/studio/web/hooks/useRunner.ts

@@ -0,0 +1,24 @@
+import { api } from "../lib/api";
+import { queryKeys } from "../lib/query-client";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* Whether the studio answers. Opened at 127.0.0.1 always yes; in the hosted one, from the hub
+   (cloud/studio). While it isn't connected the page checks again every 5 s, and the SSE reconnecting
+   rereads everything. */
+export function useRunner() {
+  const { data, reload, isFetching } = useLiveQuery(queryKeys.runner, () => api.runner.$get());
+  return {
+    /** the page is the hosted studio's (not 127.0.0.1): /runner and /exit exist */
+    hosted: data?.local === false,
+    /** null until the first answer */
+    online: data ? data.online : null,
+    name: data?.name ?? null,
+    /** while away: when it was last connected, and what kept it out (cloud/studio/src/presence.mjs) */
+    lastSeen: data?.last_seen ?? null,
+    problem: data?.problem ?? null,
+    /** a check is in flight (the "Tentar de novo" button) */
+    checking: isFetching,
+    /** asks now instead of waiting for the next check */
+    check: reload,
+  };
+}

package/studio/web/hooks/useSaveAction.ts

@@ -0,0 +1,23 @@
+/* A settings POST with its result: `result` feeds ResultMessage, `onSave` runs after an ok.
+   `save` takes the typed client call (lib/api), e.g. save(() => api.settings.key.$post({ json })). */
+
+import { useState } from "react";
+import type { ClientResponse } from "hono/client";
+import { send, type ActionResult } from "../lib/api";
+
+export function useSaveAction(onSave: () => void) {
+  const [result, setResult] = useState<ActionResult>(null);
+  const [saving, setSaving] = useState(false);
+  const save = async <R extends ClientResponse<unknown, number, "json" | "text" | "redirect">>(
+    request: () => Promise<R>,
+  ) => {
+    setSaving(true);
+    setResult(null);
+    const r = await send(request());
+    setResult(r);
+    setSaving(false);
+    if (r.ok) onSave();
+    return r.ok;
+  };
+  return { result, saving, save };
+}

package/studio/web/hooks/useSchedule.ts

@@ -0,0 +1,11 @@
+import { api } from "../lib/api";
+import { queryKeys } from "../lib/query-client";
+import type { Schedule } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* GET /api/publish/schedule (`publish.mjs scheduler --json`); refetched on SSE "video" notices */
+export function useSchedule() {
+  const { data, error, reload } = useLiveQuery(queryKeys.schedule, () => api.publish.schedule.$get());
+  const schedule: Schedule | null = data;
+  return { schedule, error, reload };
+}

package/studio/web/hooks/useServices.ts

@@ -0,0 +1,10 @@
+import { api } from "../lib/api";
+import { queryKeys } from "../lib/query-client";
+import type { Services } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* voice providers, VoiceStudio, Premiere and memory; the SSE "services" event pushes them whole */
+export function useServices(): Services | null {
+  const services: Services | null = useLiveQuery(queryKeys.services, () => api.services.$get()).data;
+  return services;
+}

package/studio/web/hooks/useSessions.ts

@@ -0,0 +1,15 @@
+import { api } from "../lib/api";
+import { queryKeys } from "../lib/query-client";
+import type { Session } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* the studio sessions; the SSE "sessions" event pushes the list whole */
+export function useSessions(): Session[] | null {
+  const sessions: Session[] | null = useLiveQuery(queryKeys.sessions, () => api.sessions.$get()).data;
+  return sessions;
+}
+
+/* the most recent studio session for a video, a reference, the channel analysis or an edit */
+export function useSessionFor(type: Session["type"], target: string): Session | null {
+  return useSessions()?.find(s => s.type === type && s.target === target) ?? null;
+}

package/studio/web/hooks/useSettings.ts

@@ -0,0 +1,11 @@
+import { api } from "../lib/api";
+import { queryKeys } from "../lib/query-client";
+import type { Settings } from "../types/api";
+import { useLiveQuery } from "./useLiveQuery";
+
+/* GET /api/settings; reload (or invalidate(queryKeys.settings)) after a POST */
+export function useSettings() {
+  const { data, error, reload } = useLiveQuery(queryKeys.settings, () => api.settings.$get());
+  const settings: Settings | null = data;
+  return { settings, error, reload };
+}

package/studio/web/hooks/useSettingsSection.ts

@@ -0,0 +1,30 @@
+/* One config section of Configurações → Publicação (`publish.<section>`): local values until
+   saved, with the changed flag, discard and save. */
+
+import { useEffect, useState } from "react";
+import { api } from "../lib/api";
+import { useSaveAction } from "./useSaveAction";
+
+export function useSettingsSection<T extends Record<string, unknown>>(
+  section: string,
+  current: T,
+  onSave: () => void,
+  toPayload: (v: T) => Record<string, unknown> = v => v,
+) {
+  const [values, setValues] = useState<T>(current);
+  const { result, saving, save } = useSaveAction(onSave);
+  const key = JSON.stringify(current);
+  useEffect(() => {
+    setValues(current);
+  }, [key]);
+  return {
+    values,
+    changed: JSON.stringify(values) !== key,
+    saving,
+    result,
+    set: <K extends keyof T>(k: K, value: T[K]) => setValues(s => ({ ...s, [k]: value })),
+    discard: () => setValues(current),
+    save: (over?: Partial<T>) =>
+      save(() => api.settings.publish.$post({ json: { section, values: toPayload({ ...values, ...over }) } })),
+  };
+}