@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/desk/ui/metrics-math.js

@@ -0,0 +1,135 @@
+// Pure rules for the Metrics page. No DOM. The page never invents a number:
+//   - a value the platform did not return is null and stays null (rendered as an em dash),
+//   - totals and averages run over known values only and always carry "N of M",
+//   - a field the official API does not expose is labelled, never guessed.
+// Retention is a percent from 0 to 100, as the platform returns it. It is never rescaled.
+
+export const DASH = "—";
+export const DRY_RUN_ID = "dry-run";
+
+const NAMES = { youtube: "YouTube", tiktok: "TikTok", instagram: "Instagram", facebook: "Facebook" };
+export const platformLabel = (p) => NAMES[p] || (p ? p[0].toUpperCase() + p.slice(1) : "the platform");
+
+// What each platform's official API returns for a published post (docs/STAGE-SPECS.md, Analytics).
+// "returned": the collector asks for it; a null means the read gave nothing back.
+// "not_exposed": the official API never returns it, so null always means "cannot be known".
+const EXPOSURE = {
+  youtube: { views: "returned", watchTimeSec: "returned", retention: "returned", estimatedRevenue: "returned" },
+  tiktok: { views: "returned", watchTimeSec: "not_exposed", retention: "not_exposed", estimatedRevenue: "not_exposed" },
+  instagram: { views: "returned", watchTimeSec: "not_exposed", retention: "not_exposed", estimatedRevenue: "not_exposed" },
+  facebook: { views: "returned", watchTimeSec: "returned", retention: "not_exposed", estimatedRevenue: "not_exposed" },
+};
+
+export function exposure(platform, field) {
+  return (EXPOSURE[platform] || {})[field] || "returned";
+}
+
+/** The muted label under a "—", or "" when the platform simply returned nothing this time. */
+export function gapLabel(m, field) {
+  if (field === "estimatedRevenue") {
+    if (m.estimatedRevenue != null && m.revenueStatus === "present") return "";
+    if (m.revenueStatus === "forbidden") return "forbidden: not available from the official API";
+    return "not available from the official API";
+  }
+  if (m[field] != null) return "";
+  if (exposure(m.platform, field) === "not_exposed") return `not exposed by the ${platformLabel(m.platform)} API`;
+  return `${platformLabel(m.platform)} returned no value`;
+}
+
+/** Sum over known values only. total is null when nothing is known. */
+export function sumKnown(values) {
+  const known = values.filter((v) => typeof v === "number" && Number.isFinite(v));
+  return { total: known.length ? known.reduce((a, b) => a + b, 0) : null, known: known.length, of: values.length };
+}
+
+/** Mean over known values only. mean is null when nothing is known. */
+export function meanKnown(values) {
+  const s = sumKnown(values);
+  return { mean: s.total === null ? null : s.total / s.known, known: s.known, of: s.of };
+}
+
+export function compact(n) {
+  if (n == null || !Number.isFinite(n)) return DASH;
+  const abs = Math.abs(n);
+  const f = (x, unit) => `${(Math.round(x * 10) / 10).toString()}${unit}`;
+  if (abs >= 1e9) return f(n / 1e9, "B");
+  if (abs >= 1e6) return f(n / 1e6, "M");
+  if (abs >= 1e4) return f(n / 1e3, "K");
+  return Number(n).toLocaleString("en-US");
+}
+
+export const percent = (r) => (r == null || !Number.isFinite(r) ? DASH : `${Math.round(r * 10) / 10}%`);
+
+export const isDryRun = (externalId) => !externalId || externalId === DRY_RUN_ID;
+
+/**
+ * One row per post: every measured post, plus every published post that has no reading yet,
+ * plus dry-run publications (which are never measured, and say why).
+ */
+export function buildRows(metrics, publications) {
+  const rows = new Map();
+  for (const m of metrics || []) rows.set(`${m.platform}:${m.externalId}`, { kind: "measured", platform: m.platform, externalId: m.externalId, metric: m, reason: "" });
+  for (const p of publications || []) {
+    if (isDryRun(p.externalId)) {
+      rows.set(`dry:${p.id}`, { kind: "dry_run", platform: p.platform, externalId: p.externalId, metric: null, reason: "Dry run: nothing was published, so there is nothing to measure." });
+      continue;
+    }
+    const key = `${p.platform}:${p.externalId}`;
+    if (!rows.has(key)) rows.set(key, { kind: "unmeasured", platform: p.platform, externalId: p.externalId, metric: null, reason: "Not measured yet. Run analytics once the post is live." });
+  }
+  return [...rows.values()];
+}
+
+/** Aggregates over live (non dry-run) posts, each with its known/total count. */
+export function summarize(rows) {
+  const live = rows.filter((r) => r.kind !== "dry_run");
+  const metrics = live.map((r) => r.metric);
+  const pick = (field) => metrics.map((m) => (m ? m[field] : null));
+  const captured = metrics.filter(Boolean).map((m) => m.capturedAt).filter(Boolean).sort();
+  return {
+    posts: live.length,
+    dryRuns: rows.length - live.length,
+    measured: metrics.filter(Boolean).length,
+    views: sumKnown(pick("views")),
+    watch: meanKnown(pick("watchTimeSec")),
+    retention: meanKnown(pick("retention")),
+    asOf: captured.length ? captured[captured.length - 1] : null,
+  };
+}
+
+/** "12.4K views across 3 of 5 posts", or an honest "no views reported". */
+export function describeSum(s, noun, posts = "posts") {
+  if (s.total === null) return `No ${noun} reported by any of ${s.of} ${posts}`;
+  return `${compact(s.total)} ${noun} across ${s.known} of ${s.of} ${posts}`;
+}
+
+// ---- Trends: views gained between a post's two latest snapshots ----
+
+/**
+ * Views gained by one post between its two latest snapshots (any input order).
+ * gained is null, never 0, when it cannot be known: fewer than two snapshots, or either reading has no view count.
+ */
+export function viewsGained(snapshots) {
+  const rows = (snapshots || []).filter((s) => s && s.capturedAt).sort((a, b) => (a.capturedAt < b.capturedAt ? 1 : a.capturedAt > b.capturedAt ? -1 : 0));
+  if (rows.length < 2) return { gained: null, from: null, to: rows[0] ? rows[0].capturedAt : null, reason: rows.length ? "one_snapshot" : "no_snapshot" };
+  const [latest, previous] = rows;
+  const known = typeof latest.views === "number" && typeof previous.views === "number" && Number.isFinite(latest.views) && Number.isFinite(previous.views);
+  return { gained: known ? latest.views - previous.views : null, from: previous.capturedAt, to: latest.capturedAt, reason: known ? "ok" : "unknown_views" };
+}
+
+/** Combines per-post results for one series and platform. Totals run over known gains only and carry "N of M". */
+export function summarizeGains(results) {
+  const s = sumKnown(results.map((r) => r.gained));
+  const known = results.filter((r) => r.gained !== null);
+  const times = (key) => known.map((r) => r[key]).filter(Boolean).sort();
+  let reason = "ok";
+  if (s.total === null) reason = results.length === 0 || results.every((r) => r.reason === "no_snapshot") ? "not_measured" : results.some((r) => r.reason === "unknown_views") ? "unknown_views" : "one_snapshot";
+  return { gained: s.total, known: s.known, of: s.of, asOf: times("to").slice(-1)[0] || null, since: times("from")[0] || null, reason };
+}
+
+export const TREND_REASONS = {
+  ok: "",
+  not_measured: "Not measured yet. Run analytics once the post is live.",
+  one_snapshot: "Only one reading so far. Gains need two.",
+  unknown_views: "The platform returned no view count for one of the two readings.",
+};

package/src/desk/ui/theme.js

@@ -0,0 +1,5 @@
+// Runs before first paint: apply the saved theme (if any) so the page never flashes the wrong one.
+try {
+  const t = localStorage.getItem("vfrey-desk-theme");
+  if (t === "light" || t === "dark") document.documentElement.dataset.theme = t;
+} catch { /* storage unavailable: follow the system */ }

package/src/desk/ui/views-creators.js

@@ -0,0 +1,209 @@
+// Creators: find creators in a niche, read a profile (stats, formats, hooks, top posts), keep watchlists, see breakouts,
+// and "Study formats" for the agent. The browser talks only to this desk's own /api/creators routes. The vfrey token stays on the server.
+import { html, icon, setHtml, $, $$, read, api, toast, refusalToast } from "./core.js";
+import { emptyState, platformName } from "./components.js";
+
+const DASH = "—";
+const short = (n) => (typeof n === "number" && Number.isFinite(n) ? (n >= 1e6 ? `${(n / 1e6).toFixed(1).replace(/\.0$/, "")}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1).replace(/\.0$/, "")}K` : String(Math.round(n))) : DASH);
+const pct = (f) => (typeof f === "number" && Number.isFinite(f) ? `${(f * 100).toFixed(1).replace(/\.0$/, "")}%` : DASH);
+const signed = (f) => (typeof f === "number" && Number.isFinite(f) ? `${f >= 0 ? "+" : ""}${pct(f)}` : DASH);
+const safeUrl = (u) => (/^https?:\/\//i.test(String(u || "")) ? u : "");
+const basis = (b) => (b === "views" ? "of views" : b === "followers" ? "of followers" : "(basis unknown)");
+const offline = () => ({ ok: false, refusal: "The desk could not be reached.", fix: "Check that `npx vfrey dashboard` is still running.", code: "offline" });
+const get = (path) => read(path).catch(offline);
+const SORTS = ["engagement", "growth", "views", "followers"];
+const TABS = [["search", "Find"], ["watchlists", "Watchlists"], ["alerts", "Alerts"]];
+
+export function creatorsView() {
+  let root;
+  const m = {
+    tab: "search", niches: [], filters: { niche: "", platform: "", followers: "", postsPerWeek: "", engagement: "", sort: "engagement" },
+    results: null, searching: false, error: null, profile: null, profileBusy: false,
+    watchlists: null, openList: null, items: null, alerts: null, alertsBusy: false, study: null, watchTo: "",
+  };
+
+  const stateBox = (err) => {
+    const out = err.code === "not_signed_in" || err.code === "unauthorized" || err.code === "not_live";
+    const cmd = out ? html`<p><code data-testid="login-command">npx vfrey login</code></p>` : "";
+    return html`<div class="panel" data-testid="creators-state" data-state="${err.code || "error"}">${emptyState("alert", out ? "Sign in to find creators" : err.code === "plan_required" ? "Creators needs the Research plan" : "Creators are not available", err.refusal || "Something went wrong.", html`${cmd}<p class="hint">${err.fix || ""}</p>`)}</div>`;
+  };
+
+  const filterForm = () => html`<section class="panel"><div class="panel-body"><form id="c-form" class="stack" style="gap:12px">
+    <div class="add-row" style="grid-template-columns:repeat(auto-fit,minmax(150px,1fr))">
+      <label class="field"><span class="muted">Niche</span><select id="f-niche" name="niche" aria-label="Niche"><option value="">Any niche</option>${m.niches.map((n) => html`<option value="${n.id}" ${n.id === m.filters.niche ? "selected" : ""}>${n.name}</option>`)}</select></label>
+      <label class="field"><span class="muted">Platform</span><select name="platform" aria-label="Platform"><option value="">All platforms</option>${["tiktok", "instagram", "youtube"].map((p) => html`<option value="${p}" ${p === m.filters.platform ? "selected" : ""}>${platformName(p)}</option>`)}</select></label>
+      <label class="field"><span class="muted">Followers</span><input type="text" name="followers" aria-label="Followers" placeholder="10k-200k" value="${m.filters.followers}"></label>
+      <label class="field"><span class="muted">Posts per week</span><input type="text" name="postsPerWeek" aria-label="Posts per week" placeholder="3" value="${m.filters.postsPerWeek}"></label>
+      <label class="field"><span class="muted">Engagement</span><input type="text" name="engagement" aria-label="Engagement" placeholder="4%" value="${m.filters.engagement}"></label>
+      <label class="field"><span class="muted">Sort by</span><select name="sort" aria-label="Sort by">${SORTS.map((s) => html`<option value="${s}" ${s === m.filters.sort ? "selected" : ""}>${s}</option>`)}</select></label>
+    </div>
+    <div><button type="submit" class="btn" ${m.searching ? "disabled" : ""}>${icon("search")}Search</button> <span class="hint">A search uses credits; see your balance with <code>npx vfrey whoami</code>.</span></div>
+  </form></div></section>`;
+
+  const resultsTable = () => {
+    if (m.searching) return html`<p class="muted" style="padding:20px">Searching…</p>`;
+    if (!m.results) return html`<section class="panel"><p class="muted" style="padding:20px">Set filters and press Search to find creators.</p></section>`;
+    if (!m.results.length) return html`<section class="panel"><p class="muted" style="padding:20px" data-testid="creators-empty">No creators match. Loosen a filter, or try another niche.</p></section>`;
+    return html`<section class="panel"><div class="panel-head"><h2>Creators</h2><span class="sub">${DASH} means not known yet. Engagement is a share of views or of followers; do not compare across the two.</span></div>
+      <div class="table-wrap"><table data-testid="creators-table"><thead><tr><th>Creator</th><th>Platform</th><th>Followers</th><th>Engagement</th><th>Median views</th><th>Posts / week</th><th>30d growth</th></tr></thead><tbody>${m.results.map((c) => html`<tr data-creator="${c.platform}/${c.handle}">
+        <td><button type="button" class="btn ghost sm" data-open="${c.platform}/${c.handle}">@${c.handle}</button>${c.verified ? html` <span class="chip ok">verified</span>` : ""}</td>
+        <td>${platformName(c.platform)}</td><td>${short(c.followers)}</td>
+        <td>${typeof c.engagementRate === "number" ? html`${pct(c.engagementRate)} <span class="sub">${basis(c.engagementBasis)}</span>` : DASH}</td>
+        <td>${short(c.medianViews)}</td><td>${typeof c.postsPerWeek === "number" ? Number(c.postsPerWeek.toFixed(1)) : DASH}</td><td>${signed(c.growth30d)}</td></tr>`)}</tbody></table></div></section>`;
+  };
+
+  const profileView = () => {
+    const p = m.profile;
+    const s = p.stats || {};
+    const g = (x, fb) => (typeof x?.pct === "number" ? signed(x.pct) : typeof x?.abs === "number" ? `${x.abs >= 0 ? "+" : ""}${x.abs} followers` : signed(fb));
+    const lists = m.watchlists || [];
+    const watched = (p.watchlists || []).length > 0;
+    return html`<div class="stack" data-testid="creator-profile">
+      <p><button type="button" class="btn secondary sm" data-back>Back to results</button></p>
+      <section class="panel"><div class="panel-head"><div><h2>@${p.handle} <span class="sub">${platformName(p.platform)}${p.displayName ? ` · ${p.displayName}` : ""}${p.verified ? " · verified" : ""}</span></h2>
+        <span class="sub">Followers ${short(p.followers)} · Following ${short(p.following)} · Posts ${short(p.postCount)} · Likes ${short(p.totalLikes)}</span></div></div>
+        <div class="panel-body stack" style="gap:12px">
+          ${p.bio ? html`<p class="sub">${p.bio}</p>` : ""}
+          <div class="add-row" style="grid-template-columns:1fr auto auto">
+            <label class="field"><span class="muted">Watchlist</span><select id="c-watchlist" aria-label="Watchlist">${lists.map((l) => html`<option value="${l.name}" ${l.name === m.watchTo ? "selected" : ""}>${l.name}</option>`)}<option value="Watching" ${lists.some((l) => l.name === "Watching") ? "hidden" : ""}>Watching (new)</option></select></label>
+            <button type="button" class="btn secondary" data-watch="add" ${m.profileBusy ? "disabled" : ""}>${icon("plus")}Watch</button>
+            <button type="button" class="btn" data-study ${m.profileBusy ? "disabled" : ""}>${icon("film")}Study formats</button>
+          </div>
+          ${watched ? html`<p class="hint">On ${p.watchlists.length} of your watchlists.</p>` : ""}
+          ${m.study ? html`<p data-testid="study-done" class="sub">Wrote <code>${m.study.file}</code> (${m.study.formats} formats, ${m.study.hooks} hooks). Your agent reads it before designing a scene.</p>` : ""}
+        </div></section>
+      <section class="panel"><div class="panel-head"><h2>Stats</h2><span class="sub">${typeof s.sampleSize === "number" ? `from ${s.sampleSize} recent posts` : "sample size not known"}</span></div>
+        <div class="panel-body"><dl data-testid="creator-stats" style="display:grid;grid-template-columns:max-content 1fr;gap:6px 24px;margin:0">
+          <dt class="muted">Median views</dt><dd>${short(p.medianViews)}</dd>
+          <dt class="muted">Engagement</dt><dd>${typeof p.engagementRate === "number" ? html`${pct(p.engagementRate)} <span class="sub">${basis(p.engagementBasis)}</span>` : DASH}</dd>
+          <dt class="muted">Posts per week</dt><dd>${typeof p.postsPerWeek === "number" ? html`${Number(p.postsPerWeek.toFixed(1))} <span class="sub">${s.postsPerWeekBasis === "30d" ? "last 30 days" : s.postsPerWeekBasis === "sample" ? "over the recent posts only" : ""}</span>` : DASH}</dd>
+          <dt class="muted">Follower growth</dt><dd>7d ${g(s.growth7d, p.growth7d)} · 30d ${g(s.growth30d, p.growth30d)}</dd>
+          <dt class="muted">Median length</dt><dd>${typeof s.medianLengthSec === "number" ? `${Math.round(s.medianLengthSec)}s` : DASH}</dd>
+          <dt class="muted">Business contact</dt><dd>${p.businessContact ? html`${p.businessContact.value} <span class="sub">from their public bio</span>` : "none in their public bio"}</dd>
+        </dl></div></section>
+      <section class="panel"><div class="panel-head"><h2>Formats</h2></div>${(p.formats || []).length ? html`<ul class="evidence" style="list-style:none;padding:0 20px 16px;margin:0" data-testid="creator-formats">${p.formats.map((f) => html`<li class="sub"><b>${f.name}</b> · ${f.postCount} posts · ${(f.terms || []).join(", ")}</li>`)}</ul>` : html`<p class="muted" style="padding:0 20px 16px">None found yet.</p>`}</section>
+      <section class="panel"><div class="panel-head"><h2>Hooks</h2><span class="sub">The first sentence of their captions.</span></div>${(p.hooks || []).length ? html`<ul style="list-style:none;padding:0 20px 16px;margin:0" data-testid="creator-hooks">${p.hooks.map((h) => html`<li class="sub">“${h.text}”</li>`)}</ul>` : html`<p class="muted" style="padding:0 20px 16px">None found yet.</p>`}</section>
+      <section class="panel"><div class="panel-head"><h2>Top posts</h2></div>${(p.topPosts || []).length ? html`<ul style="list-style:none;padding:0 20px 16px;margin:0" data-testid="creator-posts">${p.topPosts.map((t) => html`<li class="sub">${safeUrl(t.url) ? html`<a href="${safeUrl(t.url)}" target="_blank" rel="noopener noreferrer">${t.url}</a>` : "(no link)"} · ${short(t.metrics?.views)} views · ${short(t.metrics?.likes)} likes${t.caption ? ` · ${String(t.caption).slice(0, 80)}` : ""}</li>`)}</ul>` : html`<p class="muted" style="padding:0 20px 16px">None found yet.</p>`}</section>
+    </div>`;
+  };
+
+  const watchlistsTab = () => {
+    if (!m.watchlists) return html`<p class="muted" style="padding:20px">Loading watchlists…</p>`;
+    const list = m.watchlists.length ? m.watchlists.map((l) => html`<div class="list-row" data-watchlist="${l.id}"><div class="grow"><p class="t"><b>${l.name}</b></p><p class="sub">${l.items} creator${l.items === 1 ? "" : "s"}</p></div><button type="button" class="btn secondary sm" data-list="${l.id}">Show</button></div>`) : html`<p class="muted" style="padding:20px" data-testid="watchlists-empty">No watchlists yet. Open a creator and press Watch.</p>`;
+    const items = m.openList && m.items ? html`<section class="panel" data-testid="watchlist-items"><div class="panel-head"><h2>${m.openList.name}</h2><span class="sub">Export it with <code>npx vfrey creators export --watchlist ${m.openList.id} &gt; watchlist.csv</code></span></div>${m.items.length ? m.items.map((i) => html`<div class="list-row" data-item="${i.platform}/${i.handle}"><div class="grow"><p class="t">@${i.handle} <span class="sub">${platformName(i.platform)} · ${short(i.followers)} followers</span></p></div><button type="button" class="btn ghost sm" data-open="${i.platform}/${i.handle}">Profile</button><button type="button" class="btn danger sm" data-unwatch="${i.platform}/${i.handle}">Remove</button></div>`) : html`<p class="muted" style="padding:20px">Nobody yet.</p>`}</section>` : "";
+    return html`<div class="stack"><section class="panel"><div class="panel-head"><h2>Watchlists</h2><span class="sub">Watching is free.</span></div>${list}</section>${items}</div>`;
+  };
+
+  const alertsTab = () => {
+    const body = m.alertsBusy ? html`<p class="muted" style="padding:20px">Checking…</p>` : !m.alerts ? html`<p class="muted" style="padding:20px">Checking alerts uses credits, so it runs when you ask.</p>`
+      : !m.alerts.alerts.length ? html`<p class="muted" style="padding:20px" data-testid="alerts-empty">No breakouts right now.</p>`
+      : m.alerts.alerts.map((b) => html`<div class="list-row" data-alert="${b.postId}"><div class="grow"><p class="t"><b>@${b.creator.handle}</b> <span class="sub">${platformName(b.creator.platform)} · ${b.multiple}x their median</span></p><p class="sub">${safeUrl(b.url) ? html`<a href="${safeUrl(b.url)}" target="_blank" rel="noopener noreferrer">${b.url}</a>` : "(no link)"} · ${short(b.views)} views (median ${short(b.medianViews)})</p></div></div>`);
+    return html`<section class="panel"><div class="panel-head"><h2>Breakouts</h2><span class="sub">${m.alerts ? `A post counts at ${m.alerts.rule?.multiple ?? 5}x the creator's median views within ${m.alerts.rule?.withinHours ?? 48} hours.` : "On creators you watch."}</span></div><div class="panel-body"><button type="button" class="btn secondary" data-check-alerts ${m.alertsBusy ? "disabled" : ""}>${icon("refresh")}Check alerts</button></div>${body}</section>`;
+  };
+
+  const draw = () => {
+    if (!root) return;
+    if (m.error) { setHtml($(root, "#c-body"), stateBox(m.error)); return; }
+    const tabs = html`<div class="filters" role="group" aria-label="Creators sections" style="margin-bottom:16px">${TABS.map(([id, label]) => html`<button type="button" class="filter" data-tab="${id}" aria-pressed="${m.tab === id}">${label}</button>`)}</div>`;
+    let main;
+    if (m.profile) main = profileView();
+    else if (m.tab === "watchlists") main = watchlistsTab();
+    else if (m.tab === "alerts") main = alertsTab();
+    else main = html`<div class="stack">${filterForm()}${resultsTable()}</div>`;
+    const keep = document.activeElement?.id;
+    setHtml($(root, "#c-body"), html`${m.profile ? "" : tabs}${main}`);
+    if (keep) document.getElementById(keep)?.focus();
+  };
+
+  const fail = (r) => { if (["not_signed_in", "unauthorized", "not_live", "offline"].includes(r.code)) { m.error = r; draw(); } else refusalToast(r); };
+
+  const loadWatchlists = async () => {
+    const r = await get("/api/creators/watchlists");
+    if (!r.ok) { if (["not_signed_in", "unauthorized", "not_live", "offline", "plan_required"].includes(r.code)) { m.error = r; draw(); } else { m.watchlists = []; refusalToast(r); } return; }
+    m.watchlists = r.watchlists;
+    if (!m.watchTo) m.watchTo = r.watchlists[0]?.name || "Watching";
+    draw();
+  };
+
+  const search = async () => {
+    const f = m.filters;
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(f)) if (v) q.set(k, v);
+    m.searching = true; draw();
+    const r = await get(`/api/creators/search?${q}`);
+    m.searching = false;
+    if (!r.ok) { m.results = null; if (r.code === "bad_request") toast(r.refusal, { kind: "error", detail: r.fix }); else fail(r); draw(); return; }
+    m.results = r.creators; draw();
+  };
+
+  const openProfile = async (key) => {
+    const [platform, handle] = key.split("/");
+    m.profileBusy = true; m.study = null;
+    const r = await get(`/api/creators/profile?platform=${encodeURIComponent(platform)}&handle=${encodeURIComponent(handle)}`);
+    m.profileBusy = false;
+    if (!r.ok) { fail(r); return; }
+    m.profile = r.profile; draw();
+  };
+
+  return {
+    title: "Creators",
+    mount(el) {
+      root = el;
+      setHtml(el, html`<div class="page-head"><div><span class="eyebrow">Desk / Creators</span><h1>Creators</h1><p class="sub">Find creators in a niche, and study the formats and hooks that work for them.</p></div></div><div id="c-body"></div>`);
+      el.addEventListener("input", (e) => { const n = e.target.name; if (n && n in m.filters) m.filters[n] = e.target.value; });
+      el.addEventListener("change", (e) => { const n = e.target.name; if (n && n in m.filters) m.filters[n] = e.target.value; if (e.target.id === "c-watchlist") m.watchTo = e.target.value; });
+      el.addEventListener("submit", (e) => { if (e.target.id === "c-form") { e.preventDefault(); search(); } });
+      el.addEventListener("click", async (e) => {
+        const t = e.target.closest("button"); if (!t) return;
+        if (t.dataset.tab) { m.tab = t.dataset.tab; draw(); if (m.tab === "watchlists") loadWatchlists(); return; }
+        if (t.dataset.open) { openProfile(t.dataset.open); return; }
+        if (t.hasAttribute("data-back")) { m.profile = null; draw(); return; }
+        if (t.dataset.list) {
+          const r = await get(`/api/creators/watchlist?id=${encodeURIComponent(t.dataset.list)}`);
+          if (!r.ok) { fail(r); return; }
+          m.openList = r.watchlist; m.items = r.items; draw(); return;
+        }
+        if (t.dataset.unwatch && m.openList) {
+          const [platform, handle] = t.dataset.unwatch.split("/");
+          const r = await api("/api/creators/watch", { action: "remove", watchlist: m.openList.name, platform, handle });
+          if (!r.ok) { refusalToast(r); return; }
+          toast(`Removed @${handle}`, { detail: m.openList.name });
+          const again = await get(`/api/creators/watchlist?id=${encodeURIComponent(m.openList.id)}`);
+          if (again.ok) m.items = again.items;
+          loadWatchlists(); return;
+        }
+        if (t.dataset.watch && m.profile) {
+          m.profileBusy = true; draw();
+          const r = await api("/api/creators/watch", { action: "add", watchlist: m.watchTo || "Watching", platform: m.profile.platform, handle: m.profile.handle });
+          m.profileBusy = false;
+          if (!r.ok) { refusalToast(r); draw(); return; }
+          m.profile.watchlists = [...new Set([...(m.profile.watchlists || []), r.watchlist.id])];
+          m.watchTo = r.watchlist.name;
+          toast(r.created ? `Watching @${m.profile.handle}` : `Already watching @${m.profile.handle}`, { detail: r.watchlist.name });
+          draw(); loadWatchlists(); return;
+        }
+        if (t.hasAttribute("data-study") && m.profile) {
+          m.profileBusy = true; draw();
+          const r = await api("/api/creators/study", { platform: m.profile.platform, handle: m.profile.handle });
+          m.profileBusy = false;
+          if (!r.ok) { refusalToast(r); draw(); return; }
+          m.study = r; toast("Formats saved for your agent", { detail: r.file }); draw(); return;
+        }
+        if (t.hasAttribute("data-check-alerts")) {
+          m.alertsBusy = true; draw();
+          const r = await get("/api/creators/alerts");
+          m.alertsBusy = false;
+          if (!r.ok) { fail(r); draw(); return; }
+          m.alerts = r; draw();
+        }
+      });
+      draw();
+      (async () => {
+        const n = await get("/api/topics/niches");
+        if (n.ok) { m.niches = n.niches; draw(); }
+        loadWatchlists();
+      })();
+    },
+    update() {},
+  };
+}

package/src/desk/ui/views-keys.js

@@ -0,0 +1,114 @@
+// Account keys: one form per platform. Write only. A saved value is never shown again.
+import { html, setHtml, $, $$, api, toast, refusalToast, store, rel, abs } from "./core.js";
+import { emptyState } from "./components.js";
+
+// Which stored fields each platform needs. `account` fields belong to the account, `series` fields to each of its series.
+const GROUPS = [
+  { key: "youtube", name: "YouTube", account: ["youtubeApiKey"], series: ["googleClientId", "googleClientSecret", "youtubeRefreshToken"] },
+  { key: "tiktok", name: "TikTok", account: ["tiktokClientKey", "tiktokClientSecret"], series: ["tiktokRefreshToken", "tiktokOpenId"] },
+  { key: "instagram", name: "Instagram", account: ["metaAppId", "metaAppSecret"], series: ["igUserId", "igAccessToken"], note: "The Meta app id and secret also serve Facebook." },
+  { key: "facebook", name: "Facebook", account: [], series: ["fbPageId", "fbPageToken"], note: "Uses the Meta app id and secret saved under Instagram." },
+  { key: "reddit", name: "Reddit sources", account: ["redditClientId", "redditClientSecret"], series: [] },
+];
+
+export function keysView() {
+  let root, accountId = null, shape = "", confirming = null;
+  const creds = () => store.state?.credentials || [];
+  const find = (kind, owner, field) => creds().find((c) => c.ownerKind === kind && c.ownerId === owner && c.field === field);
+  const seriesOf = (acc) => (store.state?.series || []).filter((x) => x.accountId === acc);
+  const key = (kind, owner, field) => `${kind}|${owner}|${field}`;
+
+  function row(kind, owner, field) {
+    const k = key(kind, owner, field);
+    return html`<div class="sec-row" data-secret="${k}"><div class="sec-name"><label for="k-${k}"><span class="mono">${field}</span></label><span class="chip warn" data-state>Missing</span><span class="sub" data-when></span></div>
+      <div class="sec-form"><input type="password" id="k-${k}" data-field="${k}" autocomplete="new-password" spellcheck="false" placeholder="Leave blank to keep" aria-label="${field} value"><span data-clear></span></div></div>`;
+  }
+
+  function build(s) {
+    const accs = s.accounts || [];
+    const acc = accs.find((a) => a.id === accountId) || accs[0];
+    accountId = acc?.id ?? null;
+    if (!acc) {
+      setHtml($(root, "#keys-body"), html`<div class="panel">${emptyState("series", "No account yet", "Create an account and a series first. Keys belong to an account and its series.")}</div>`);
+      return;
+    }
+    const series = seriesOf(acc.id);
+    const picker = accs.length > 1 ? html`<div class="field" style="max-width:320px"><label for="acct">Account</label><select id="acct">${accs.map((a) => html`<option value="${a.id}" ${a.id === acc.id ? "selected" : ""}>${a.name}</option>`)}</select></div>` : "";
+    setHtml($(root, "#keys-body"), html`<div class="stack">${picker}${GROUPS.map((g) => html`
+      <form class="panel" data-group="${g.key}"><div class="panel-head"><h2>${g.name}</h2><span class="sub">${g.note || "Account " + acc.name}</span></div><div class="panel-body">
+        ${g.account.length ? html`<p class="group-label">Account · ${acc.name}</p>${g.account.map((f) => row("account", acc.id, f))}` : ""}
+        ${g.series.length ? series.map((x) => html`<p class="group-label">Series · ${x.id}</p>${g.series.map((f) => row("series", x.id, f))}`) : ""}
+        ${g.series.length && !series.length && !g.account.length ? html`<p class="muted">This account has no series yet.</p>` : ""}
+        <div class="form-foot"><button type="submit" class="btn">Save ${g.name} keys</button><span class="hint">Blank fields keep what is stored.</span></div></div></form>`)}</div>`);
+  }
+
+  function paint() {
+    for (const r of $$(root, "[data-secret]")) {
+      const [kind, owner, field] = r.dataset.secret.split("|");
+      const c = find(kind, owner, field);
+      const chip = $(r, "[data-state]");
+      chip.className = `chip ${c ? "ok" : "warn"}`;
+      chip.textContent = c ? "Present" : "Missing";
+      const when = $(r, "[data-when]");
+      when.textContent = c ? (c.setAt ? `Set ${rel(c.setAt)}` : "Set earlier") : "";
+      when.title = c?.setAt ? abs(c.setAt) : "";
+      const k = r.dataset.secret;
+      const slot = $(r, "[data-clear]");
+      if (!c) setHtml(slot, html``);
+      else if (confirming === k) setHtml(slot, html`<span class="confirm" role="group" aria-label="Confirm clear">Clear ${field}?<button type="button" class="btn danger solid sm" data-act="clear-yes" data-k="${k}">Yes, clear</button><button type="button" class="btn ghost sm" data-act="clear-no">Keep it</button></span>`);
+      else setHtml(slot, html`<button type="button" class="btn secondary sm" data-act="clear" data-k="${k}">Clear</button>`);
+    }
+  }
+
+  return {
+    title: "Keys",
+    mount(el) {
+      root = el;
+      setHtml(el, html`<div class="page-head"><div><span class="eyebrow">Desk / Keys</span><h1>Keys</h1><p class="sub">Platform keys for this project, stored sealed. A saved value is never shown again; this page only says whether it is present.</p></div></div><div id="keys-body"></div>`);
+      el.addEventListener("change", (e) => {
+        if (e.target.id !== "acct") return;
+        accountId = e.target.value; shape = ""; confirming = null;
+        if (store.state) this.update(store.state);
+      });
+      el.addEventListener("submit", async (e) => {
+        const form = e.target.closest("form[data-group]");
+        if (!form) return;
+        e.preventDefault();
+        const filled = $$(form, "input[data-field]").filter((i) => i.value.trim() !== "");
+        if (!filled.length) { toast("Nothing to save", { detail: "Blank fields keep the stored value." }); return; }
+        let saved = 0;
+        for (const input of filled) {
+          const [ownerKind, ownerId, field] = input.dataset.field.split("|");
+          const value = input.value;
+          input.value = "";
+          const r = await api("/api/secrets", { ownerKind, ownerId, field, value });
+          if (!r.ok) { refusalToast(r); for (const i of filled) i.value = ""; return; }
+          saved += 1;
+        }
+        toast(`${saved} key${saved === 1 ? "" : "s"} saved`);
+        store.refresh?.();
+      });
+      el.addEventListener("click", async (e) => {
+        const b = e.target.closest("[data-act]");
+        if (!b) return;
+        if (b.dataset.act === "clear") { confirming = b.dataset.k; paint(); }
+        if (b.dataset.act === "clear-no") { confirming = null; paint(); }
+        if (b.dataset.act === "clear-yes") {
+          const [ownerKind, ownerId, field] = b.dataset.k.split("|");
+          confirming = null;
+          const r = await api("/api/secrets/clear", { ownerKind, ownerId, field });
+          if (!r.ok) { paint(); return refusalToast(r); }
+          toast(`${field} cleared`);
+          store.refresh?.();
+        }
+      });
+    },
+    update(s) {
+      const accs = s.accounts || [];
+      const acc = accs.find((a) => a.id === accountId) || accs[0];
+      const next = `${acc?.id}|${accs.map((a) => a.id).join(",")}|${seriesOf(acc?.id).map((x) => x.id).join(",")}`;
+      if (next !== shape) { shape = next; build(s); }
+      if (acc) paint();
+    },
+  };
+}