@crievo/omni 0.0.0-stage → 0.1.0

package/studio/web/lib/analytics-metrics.ts

@@ -0,0 +1,351 @@
+/* Analytics page helpers: number formats, the metric definitions (used by the table, comparison,
+   bar chart, cards and the all-metrics accordion), the tabs, periods and milestones, and the parser
+   of the last channel analysis (channel/analyses/<day>.md). Numbers come from tools/analysis.mjs
+   (over tools/metrics.mjs, collected hourly by the launchd agent). */
+
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import type { ChartConfig } from "../components/ui/chart";
+import {
+  Activity,
+  Bookmark,
+  ChatCircleText,
+  Clock,
+  Eye,
+  FastForward,
+  FilmStrip,
+  Flag,
+  Heart,
+  Lightbulb,
+  ListChecks,
+  Microscope,
+  Notepad,
+  Radar,
+  ShareNetwork,
+  Table,
+  Target,
+  Users,
+} from "../components/icons";
+import type { ComparableMetric, MetricsSnapshot, ReelMetrics } from "../types/api";
+
+/* --- formats ------------------------------------------------------------------------- */
+export const fmtNum = (v: number | null | undefined, decimals = 0) =>
+  v == null ? "—" : v.toLocaleString("pt-BR", { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+export const fmtPct = (v: number | null | undefined) => (v == null ? "—" : `${fmtNum(v, 1)}%`);
+export const fmtSec = (v: number | null | undefined) => (v == null ? "—" : `${fmtNum(v, 1)} s`);
+export const fmtAge = (h: number | null | undefined) =>
+  h == null ? "—" : h < 48 ? `${Math.round(h)} h` : `${Math.round(h / 24)} d`;
+export const fmtDay = (d: string) => `${d.slice(8, 10)}/${d.slice(5, 7)}`;
+export const dayOf = (t: number) => new Date(t).toLocaleDateString("pt-BR", { day: "2-digit", month: "2-digit" });
+export const hourOf = (t: number) => new Date(t).toLocaleTimeString("pt-BR", { hour: "2-digit", minute: "2-digit" });
+export const shortLabel = (t: string, n = 30) => (t.length > n ? `${t.slice(0, n - 1).trimEnd()}…` : t);
+/* compact for an axis: 26 mil, 25,5 mil: the decimal shows only when it exists (the axis doesn't
+   repeat "26 mil" for 25,500 and 26,000) */
+export const compact = (v: number) => {
+  if (v < 1000) return fmtNum(v);
+  const k = v / 1000;
+  return `${fmtNum(k, Number.isInteger(Math.round(k * 10) / 10) ? 0 : 1)} mil`;
+};
+/* count Y axis: compact only when it doesn't repeat the same label (2,120 to 2,130 became five
+   "2,1 mil"); below 10 mil, or with the whole curve within 2% of the top, the whole number */
+export const fmtAxisY = (values: number[]) => {
+  const max = Math.max(...values),
+    min = Math.min(...values);
+  return max < 10_000 || max - min < max * 0.02 ? (v: number) => fmtNum(v) : compact;
+};
+export const perThousand = (n: number | null | undefined, views: number | null | undefined) =>
+  n == null || !views ? null : (n / views) * 1000;
+
+export function median(values: number[]) {
+  const v = [...values].sort((a, b) => a - b);
+  if (!v.length) return null;
+  const m = v.length >> 1;
+  return v.length % 2 ? v[m] : (v[m - 1] + v[m]) / 2;
+}
+
+/* an element's width, so the y bar axis fits on a phone */
+export function useWidth<T extends HTMLElement>() {
+  const ref = useRef<T>(null);
+  const [width, setWidth] = useState(0);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const ro = new ResizeObserver(([e]) => setWidth(e.contentRect.width));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  return [ref, width] as const;
+}
+
+/* --- the metrics, once ------------------------------------------------------------------- */
+export type MetricId =
+  | "views"
+  | "reach"
+  | "likes"
+  | "skip"
+  | "watched"
+  | "watched_s"
+  | "saves_per_k"
+  | "shares_per_k"
+  | "comments_per_k"
+  | "saves"
+  | "shares"
+  | "comments"
+  | "interactions"
+  | "total_watch";
+/* `median`: the key in Medians; `lowerIsBetter`: skip; `judges`: what the metric judges (shown in hints) */
+export type MetricDef = {
+  name: string;
+  of: (s: MetricsSnapshot) => number | null;
+  fmt: (v: number) => string;
+  median?: ComparableMetric;
+  lowerIsBetter?: boolean;
+  judges?: string;
+};
+export const METRICS: Record<MetricId, MetricDef> = {
+  views: { name: "Views", of: s => s.views, fmt: v => fmtNum(v), median: "views", judges: "o alcance" },
+  reach: { name: "Alcance", of: s => s.reach, fmt: v => fmtNum(v), median: "reach" },
+  likes: { name: "Curtidas", of: s => s.likes, fmt: v => fmtNum(v), median: "likes" },
+  skip: {
+    name: "Pulam em 3 s",
+    of: s => s.skip_3s_pct,
+    fmt: v => fmtPct(v),
+    median: "skip_3s_pct",
+    lowerIsBetter: true,
+    judges: "o gancho: quadro 0 e primeira frase",
+  },
+  watched: {
+    name: "% assistido",
+    of: s => s.watched_pct,
+    fmt: v => fmtPct(v),
+    median: "watched_pct",
+    judges: "o miolo",
+  },
+  watched_s: { name: "Assistido médio", of: s => s.avg_watch_s, fmt: v => fmtSec(v), median: "avg_watch_s" },
+  saves_per_k: {
+    name: "Salvos/mil",
+    of: s => perThousand(s.saves, s.views),
+    fmt: v => fmtNum(v, 1),
+    median: "saves_per_k",
+    judges: "a utilidade",
+  },
+  shares_per_k: {
+    name: "Compart./mil",
+    of: s => perThousand(s.shares, s.views),
+    fmt: v => fmtNum(v, 1),
+    median: "shares_per_k",
+    judges: "o tema",
+  },
+  comments_per_k: {
+    name: "Coment./mil",
+    of: s => perThousand(s.comments, s.views),
+    fmt: v => fmtNum(v, 1),
+    median: "comments_per_k",
+    judges: "o CTA",
+  },
+  saves: { name: "Salvos", of: s => s.saves, fmt: v => fmtNum(v), median: "saves" },
+  shares: { name: "Compartilhamentos", of: s => s.shares, fmt: v => fmtNum(v), median: "shares" },
+  comments: { name: "Comentários", of: s => s.comments, fmt: v => fmtNum(v), median: "comments" },
+  interactions: { name: "Interações", of: s => s.interactions, fmt: v => fmtNum(v) },
+  total_watch: { name: "Tempo total assistido", of: s => s.total_watch_h, fmt: v => `${fmtNum(v, 1)} h` },
+};
+
+/* each metric's icon, in the tabs */
+export type IconComponent = (p: { "aria-hidden"?: boolean | "true" | "false" }) => ReactNode;
+export const METRIC_ICON: Record<MetricId, IconComponent> = {
+  views: Eye,
+  reach: Radar,
+  likes: Heart,
+  skip: FastForward,
+  watched: Clock,
+  watched_s: Clock,
+  saves_per_k: Bookmark,
+  shares_per_k: ShareNetwork,
+  comments_per_k: ChatCircleText,
+  saves: Bookmark,
+  shares: ShareNetwork,
+  comments: ChatCircleText,
+  interactions: Activity,
+  total_watch: Clock,
+};
+export const metricValue = (r: ReelMetrics, id: MetricId) => (r.current ? METRICS[id].of(r.current) : null);
+
+/* a card's trend: "+12,3%" (or percentage points), up or down, good/bad/neutral */
+export type Trend = { text: string; up: boolean; good: boolean | null };
+export function variation(
+  value: number | null | undefined,
+  ref: number | null | undefined,
+  lowerIsBetter = false,
+  inPoints = false,
+): Trend | null {
+  if (value == null || ref == null || (!inPoints && ref === 0)) return null;
+  const d = inPoints ? value - ref : ((value - ref) / ref) * 100;
+  if (Math.abs(d) < 0.05) return { text: inPoints ? "0 p.p." : "0%", up: true, good: null };
+  return {
+    text: `${d > 0 ? "+" : ""}${fmtNum(d, 1)}${inPoints ? " p.p." : "%"}`,
+    up: d > 0,
+    good: d > 0 !== lowerIsBetter,
+  };
+}
+
+/* --- charts ------------------------------------------------------------------------------ */
+export const DAY_MS = 86_400_000;
+export const axisProps = { tickLine: false, axisLine: false, tickMargin: 8 } as const;
+/* no animation: the panel shows numbers, not an effect; and a background tab freezes
+   requestAnimationFrame, which left the chart stuck on the first frame */
+export const noAnimation = { isAnimationActive: false } as const;
+
+/* channel progression (dashboard-01's ChartAreaInteractive, as a wave line with area) */
+export type ProgressionId = "views" | "comments" | "saves" | "followers";
+export type Period = "24h" | "7d" | "30d";
+export const PROGRESSION: { id: ProgressionId; name: string; description: string; Icon: IconComponent }[] = [
+  { id: "views", name: "Views", description: "Views somadas de todos os Reels, a cada coleta", Icon: Eye },
+  {
+    id: "comments",
+    name: "Comentários",
+    description: "Comentários somados de todos os Reels, a cada coleta",
+    Icon: ChatCircleText,
+  },
+  { id: "saves", name: "Salvos", description: "Salvos somados de todos os Reels, a cada coleta", Icon: Bookmark },
+  { id: "followers", name: "Seguidores", description: "Seguidores da conta, a cada coleta", Icon: Users },
+];
+export const PERIODS: { id: Period; name: string; ms: number }[] = [
+  { id: "24h", name: "24 h", ms: DAY_MS },
+  { id: "7d", name: "7 dias", ms: 7 * DAY_MS },
+  { id: "30d", name: "30 dias", ms: 30 * DAY_MS },
+];
+export const BAR_METRICS: MetricId[] = ["skip", "watched", "saves_per_k", "shares_per_k", "comments_per_k", "views"];
+
+/* --- the Reels table ----------------------------------------------------------------------
+   A column's cell is `text(r)` (null → a muted "—"); with `metric`, the page adds VsMedian
+   (the comparison with the median) after the text. */
+export type Column = {
+  id: string;
+  name: string;
+  value: (r: ReelMetrics) => number | string | null;
+  text: (r: ReelMetrics) => string | null;
+  metric?: MetricId;
+  num?: boolean;
+  default?: boolean;
+};
+export const metricColumn = (id: MetricId, isDefault = false, name = METRICS[id].name): Column => ({
+  id,
+  name,
+  default: isDefault,
+  num: true,
+  metric: id,
+  value: r => metricValue(r, id),
+  text: r => {
+    const v = metricValue(r, id);
+    return v == null ? "—" : METRICS[id].fmt(v);
+  },
+});
+export const COLUMNS: Column[] = [
+  {
+    id: "age",
+    name: "Idade",
+    default: true,
+    num: true,
+    value: r => r.current?.age_h ?? null,
+    text: r => fmtAge(r.current?.age_h),
+  },
+  metricColumn("views", true),
+  metricColumn("skip", true),
+  metricColumn("watched", true),
+  metricColumn("saves_per_k", true),
+  metricColumn("comments_per_k", true),
+  metricColumn("reach"),
+  metricColumn("likes"),
+  metricColumn("shares_per_k"),
+  metricColumn("watched_s"),
+  { id: "duration", name: "Duração", num: true, value: r => r.duration_s, text: r => fmtSec(r.duration_s) },
+  { id: "pillar", name: "Pilar", value: r => r.pillar, text: r => r.pillar },
+  { id: "goal", name: "Objetivo", value: r => r.goal, text: r => r.goal },
+];
+export const PAGE_SIZE = 20;
+/* the "all" option of the table filters */
+export const ALL = "";
+
+export const COMPARISON_ROWS: MetricId[] = [
+  "views",
+  "skip",
+  "watched",
+  "watched_s",
+  "saves_per_k",
+  "shares_per_k",
+  "comments_per_k",
+  "reach",
+  "likes",
+];
+
+/* --- insights and plan, from the last analysis (channel/analyses/<day>.md) ------------------- */
+export type Section = { title: string; body: string };
+export function sections(md: string): { intro: string; sections: Section[] } {
+  const parts = md.split(/^## /m);
+  return {
+    intro: parts[0],
+    sections: parts.slice(1).map(p => {
+      const i = p.indexOf("\n");
+      return { title: (i < 0 ? p : p.slice(0, i)).trim(), body: i < 0 ? "" : p.slice(i + 1).trim() };
+    }),
+  };
+}
+
+/* "1. **Title.** evidence…": each item becomes an accordion; what comes after the list, a note */
+export function numberedItems(body: string) {
+  const blocks = body.split(/^\d+\.\s+/m);
+  const items: { title: string; text: string }[] = [];
+  let rest = blocks[0].trim();
+  for (const b of blocks.slice(1)) {
+    const [item, ...after] = b.trim().split(/\n\s*\n/);
+    const m = /^\*\*(.+?)\*\*\s*([\s\S]*)$/.exec(item.trim());
+    items.push(
+      m ? { title: m[1].replace(/[.:]$/, ""), text: m[2] } : { title: shortLabel(item.trim(), 80), text: item.trim() },
+    );
+    if (after.length) rest = [rest, ...after].filter(Boolean).join("\n\n");
+  }
+  return { items, rest };
+}
+
+export const POINTS_CONFIG = { reels: { label: "Reels", color: "var(--chart-1)" } } satisfies ChartConfig;
+
+/* --- tabs ------------------------------------------------------------------------------------ */
+export type ChannelTab = "reels" | "insights" | "plan" | "points";
+export const CHANNEL_TABS: { id: ChannelTab; name: string; Icon: IconComponent }[] = [
+  { id: "reels", name: "Reels", Icon: Table },
+  { id: "insights", name: "Insights", Icon: Lightbulb },
+  { id: "plan", name: "Plano", Icon: ListChecks },
+  { id: "points", name: "Gancho × miolo", Icon: Target },
+];
+
+/* a Reel's hourly wave */
+export const HOURS: MetricId[] = ["views", "reach", "skip", "watched", "saves", "shares", "comments"];
+/* age on the axis: with a step under 1 h, the minutes (37 h 15); else like fmtAge() */
+export const ageAxis = (h: number, step: number) =>
+  step < 1 && h < 48 ? `${Math.floor(h)} h ${String(Math.round((h % 1) * 60)).padStart(2, "0")}` : fmtAge(h);
+
+export type ReelTab = "diagnosis" | "opening" | "milestones" | "script";
+export const REEL_TABS: { id: ReelTab; name: string; Icon: IconComponent }[] = [
+  { id: "diagnosis", name: "Diagnóstico", Icon: Microscope },
+  { id: "opening", name: "Abertura", Icon: FilmStrip },
+  { id: "milestones", name: "Marcos", Icon: Flag },
+  { id: "script", name: "Roteiro", Icon: Notepad },
+];
+export const MILESTONES = ["1h", "3h", "24h", "72h", "7d", "30d"];
+export const MILESTONE_LABEL: Record<string, string> = {
+  "1h": "1 h",
+  "3h": "3 h",
+  "24h": "24 h",
+  "72h": "72 h",
+  "7d": "7 dias",
+  "30d": "30 dias",
+};
+export const ALL_METRICS: MetricId[] = [
+  "reach",
+  "likes",
+  "interactions",
+  "comments",
+  "shares",
+  "saves",
+  "watched_s",
+  "total_watch",
+];

package/studio/web/lib/api.ts

@@ -0,0 +1,70 @@
+/* The studio API client. `api` is typed end to end from the server's routes (hono/client over
+   api/app.ts's AppType): paths, params, query strings, JSON bodies and response bodies. Data the
+   UI keeps on screen goes through TanStack Query (hooks/*) with `read`; one-off actions use `send`.
+   Path params go through `enc` (hono/client doesn't encode them). */
+
+import { hc, type ClientResponse } from "hono/client";
+import type { AppType } from "../../api/app";
+
+export const client = hc<AppType>("/");
+export const api = client.api;
+
+/* a path param as the URL carries it */
+export const enc = encodeURIComponent;
+
+/* the common response envelope of every POST */
+export type ApiResponse = {
+  ok: boolean;
+  output?: string;
+  error?: string;
+  slug?: string;
+  session?: string;
+  id?: string;
+};
+
+/* the last result of a save action, shown by ResultMessage; null = nothing yet */
+export type ActionResult = { ok: boolean; output?: string; error?: string } | null;
+
+type AnyResponse = ClientResponse<unknown, number, "json" | "text" | "redirect">;
+/* the JSON body of a 200 (what `read` returns) / of any status (what `send` returns) */
+export type OkJson<R> = R extends ClientResponse<infer T, infer S, "json"> ? (S extends 200 ? T : never) : never;
+export type AnyJson<R> = R extends ClientResponse<infer T, number, "json"> ? T : never;
+
+/* the hosted studio's answer while the studio isn't connected to it */
+export class RunnerOffline extends Error {}
+
+/* a GET's JSON; any other status throws "<status>: <body>" (RunnerOffline when the studio isn't connected) */
+export async function read<R extends AnyResponse>(request: Promise<R>): Promise<OkJson<R>> {
+  const r = await request;
+  if (!r.ok) {
+    const body = await r.text();
+    /* the hosted studio without the studio connected (cloud/studio): the message the Worker wrote */
+    if (r.status === 503) {
+      try {
+        const j = JSON.parse(body);
+        if (j?.offline) throw new RunnerOffline(String(j.error));
+      } catch (e) {
+        if (e instanceof RunnerOffline) throw e;
+      }
+    }
+    throw new Error(`${r.status}: ${body}`);
+  }
+  return (await r.json()) as OkJson<R>;
+}
+
+/* what a POST answers: the route's own JSON, read with the envelope's optional fields */
+export type Envelope<R> = AnyJson<R> & ApiResponse;
+
+/* a POST's envelope; never throws for an HTTP error: a body that isn't JSON (the plain 404, the
+   guard's 403/415) comes back as { ok: false, error: "<status>: <statusText>" } */
+export async function send<R extends AnyResponse>(request: Promise<R>): Promise<Envelope<R>> {
+  const r = await request;
+  try {
+    return (await r.json()) as Envelope<R>;
+  } catch {
+    return { ok: false, error: `${r.status}: ${r.statusText}` } as Envelope<R>;
+  }
+}
+
+/* the message of a caught error */
+export const errorText = (e: unknown) => String((e as Error)?.message ?? e);

package/studio/web/lib/audio.ts

@@ -0,0 +1,39 @@
+/* Audio helpers shared by the players and the voice screens. */
+
+let playingNow: HTMLAudioElement | null = null;
+
+/* whoever starts playing pauses what was playing: also applies to the sequence player */
+export function claimAudio(el: HTMLAudioElement) {
+  if (playingNow && playingNow !== el) playingNow.pause();
+  playingNow = el;
+}
+export function releaseAudio(el: HTMLAudioElement | null) {
+  if (playingNow === el) playingNow = null;
+}
+
+/* a chosen file's duration; a recorder's webm comes as Infinity and becomes 0 */
+export function audioDuration(url: string): Promise<number> {
+  return new Promise(resolve => {
+    const a = new Audio();
+    a.preload = "metadata";
+    a.onloadedmetadata = () => resolve(Number.isFinite(a.duration) ? a.duration : 0);
+    a.onerror = () => resolve(0);
+    a.src = url;
+  });
+}
+
+let audioCtx: AudioContext | null = null;
+/* the <audio> sound goes through the analyser and on to the output; null if the browser refuses */
+export function createAudioAnalyser(a: HTMLAudioElement): AnalyserNode | null {
+  try {
+    audioCtx ??= new AudioContext();
+    if (audioCtx.state === "suspended") audioCtx.resume().catch(() => {});
+    const an = audioCtx.createAnalyser();
+    an.fftSize = 512;
+    audioCtx.createMediaElementSource(a).connect(an);
+    an.connect(audioCtx.destination);
+    return an;
+  } catch {
+    return null;
+  }
+}

package/studio/web/lib/avatars.ts

@@ -0,0 +1,41 @@
+/* Voice avatar seeds. The avatar is drawn from the voice id (always the same for the same voice). */
+
+/* FNV-1a hash of a text: the avatar's seed */
+export function seedOf(text: string) {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+/* mulberry32: a seeded random generator */
+export function randomSeed(seed: number) {
+  let a = seed;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/* ten avatars, one per hue (36° apart), in shuffled order and each with a shuffled drawing */
+export function shuffleAvatars(): string[] {
+  const hues = Array.from({ length: 10 }, (_, i) => (i * 36 + Math.floor(Math.random() * 12)) % 360);
+  for (let i = hues.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [hues[i], hues[j]] = [hues[j], hues[i]];
+  }
+  return hues.map(h => `h${h}-${Math.random().toString(36).slice(2, 8).padEnd(6, "0")}`);
+}
+
+/* The orb's colors for a voice: three. The same hue the voice always had (the avatar picked when
+   cloning pins it with `h<hue>-`): a vivid main color, a lighter neighbor and a deeper one. */
+export function orbPalette(seed: string): string[] {
+  const pinned = /^h(\d{1,3})-/.exec(seed);
+  const h = pinned ? Number(pinned[1]) % 360 : randomSeed(seedOf(seed))() * 360;
+  const hsl = (dh: number, s: number, l: number) => `hsl(${Math.round((h + dh + 360) % 360)} ${s}% ${l}%)`;
+  return [hsl(0, 96, 54), hsl(34, 100, 70), hsl(-30, 84, 40)];
+}