@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/desk/screens.ts

@@ -0,0 +1,149 @@
+// Read-only data for the Publications, Sources, Engage and Trends screens (spec 015 B).
+import { redact } from "../queue/seal.js";
+import type { Store } from "../queue/store.js";
+import { summarizeGains, viewsGained } from "./ui/metrics-math.js";
+
+type Row = Record<string, unknown>;
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+const strOrNull = (v: unknown): string | null => (typeof v === "string" ? v : null);
+const numOrNull = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+const PLATFORMS = ["youtube", "tiktok", "instagram", "facebook"];
+const ID = /^[A-Za-z0-9._-]{1,64}$/;
+
+export const isDry = (externalId: string | null): boolean => !externalId || externalId === "dry-run";
+
+/** A public link to the post, only where the platform's id alone is enough to build one. */
+export function externalUrl(platform: string, externalId: string | null): string | null {
+  if (isDry(externalId) || !externalId || !/^[A-Za-z0-9_-]{3,64}$/.test(externalId)) return null;
+  if (platform === "youtube") return `https://www.youtube.com/watch?v=${externalId}`;
+  if (platform === "facebook") return `https://www.facebook.com/watch/?v=${externalId}`;
+  return null;
+}
+
+const filterOf = (params: URLSearchParams, name: string, ok: (v: string) => boolean): string | null => {
+  const v = params.get(name);
+  return v && ok(v) ? v : null;
+};
+
+function seriesIds(store: Store): string[] {
+  return (store.db.prepare(`SELECT id FROM desk_series ORDER BY id`).all() as Row[]).map((r) => str(r.id));
+}
+
+export function publicationsView(store: Store, params: URLSearchParams) {
+  const series = filterOf(params, "series", (v) => ID.test(v));
+  const platform = filterOf(params, "platform", (v) => PLATFORMS.includes(v));
+  const rows = store.db
+    .prepare(`SELECT * FROM publications WHERE (? IS NULL OR account_id = ?) AND (? IS NULL OR platform = ?) ORDER BY published_at DESC, rowid DESC LIMIT 500`)
+    .all(series, series, platform, platform) as Row[];
+  return {
+    ok: true,
+    series: seriesIds(store),
+    platforms: PLATFORMS,
+    publications: rows.map((row) => {
+      let proof: Row = {};
+      try {
+        proof = JSON.parse(str(row.disclosure)) as Row;
+      } catch {
+        proof = {};
+      }
+      let audit: Row = {};
+      try {
+        audit = JSON.parse(str(row.audit)) as Row;
+      } catch {
+        audit = {};
+      }
+      const externalId = strOrNull(row.external_id);
+      const dryRun = isDry(externalId) || audit.dryRun === true;
+      return {
+        id: str(row.id),
+        jobId: str(row.job_id),
+        seriesId: str(row.account_id),
+        platform: str(row.platform),
+        title: redact(str(row.title)),
+        status: dryRun ? "dry-run" : "published",
+        dryRun,
+        externalId: dryRun ? null : externalId,
+        externalUrl: dryRun ? null : externalUrl(str(row.platform), externalId),
+        // The proof the publish stage stored: which request field carried the disclosure, and the value it held.
+        disclosure: { field: strOrNull(proof.field), value: typeof proof.value === "boolean" ? proof.value : null, location: strOrNull(proof.location) },
+        // A dry run builds the request but never sends it.
+        disclosureSent: !dryRun,
+        publishedAt: str(row.published_at),
+      };
+    }),
+  };
+}
+
+export function sourcesView(store: Store) {
+  const series = seriesIds(store);
+  const sources = (store.db.prepare(`SELECT * FROM desk_sources ORDER BY series_id, rowid`).all() as Row[]).map((row) => ({
+    id: str(row.id),
+    seriesId: str(row.series_id),
+    kind: str(row.kind),
+    value: redact(str(row.value)),
+    lastStatus: strOrNull(row.last_status),
+    lastFetchAt: strOrNull(row.last_fetch_at),
+    lastCount: numOrNull(row.last_count),
+    lastCode: strOrNull(row.last_code),
+  }));
+  const warnings = (store.db.prepare(`SELECT * FROM desk_warnings WHERE code = 'topics_unavailable' AND acked_at IS NULL ORDER BY created_at DESC LIMIT 20`).all() as Row[]).map((row) => ({
+    id: str(row.id),
+    seriesId: strOrNull(row.account_id),
+    code: str(row.code),
+    message: redact(str(row.message)),
+    createdAt: str(row.created_at),
+  }));
+  return { ok: true, series, sources, warnings };
+}
+
+export function engageView(store: Store, params: URLSearchParams) {
+  const series = filterOf(params, "series", (v) => ID.test(v));
+  const rows = store.db
+    .prepare(`SELECT * FROM comments_handled WHERE platform != 'tiktok' AND (? IS NULL OR account_id = ?) ORDER BY created_at DESC, rowid DESC LIMIT 300`)
+    .all(series, series) as Row[];
+  return {
+    ok: true,
+    series: seriesIds(store),
+    // TikTok's API has no comment reply, so no TikTok rows exist and none are shown.
+    note: "TikTok is not listed: TikTok's API does not support replying to comments.",
+    replies: rows.map((row) => ({
+      platform: str(row.platform),
+      commentId: str(row.comment_id),
+      seriesId: str(row.account_id),
+      comment: row.comment_text ? redact(str(row.comment_text)) : null,
+      reply: row.reply_text ? redact(str(row.reply_text)) : null,
+      status: str(row.action) === "replied" && Number(row.dry_run) === 1 ? "drafted" : str(row.action),
+      code: strOrNull(row.code),
+      tone: strOrNull(row.tone),
+      at: str(row.created_at),
+    })),
+  };
+}
+
+export function trendsView(store: Store) {
+  const live = (store.db.prepare(`SELECT account_id, platform, external_id FROM publications WHERE external_id IS NOT NULL AND external_id != 'dry-run'`).all() as Row[]).map((r) => ({ seriesId: str(r.account_id), platform: str(r.platform), externalId: str(r.external_id) }));
+  const snapshots = new Map<string, Array<{ capturedAt: string; views: number | null }>>();
+  for (const row of store.db.prepare(`SELECT account_id, platform, external_id, captured_at, views FROM metrics WHERE external_id != 'dry-run' ORDER BY captured_at DESC, rowid DESC`).all() as Row[]) {
+    const key = `${str(row.account_id)}\u0000${str(row.platform)}\u0000${str(row.external_id)}`;
+    const list = snapshots.get(key) ?? [];
+    if (list.length < 2) list.push({ capturedAt: str(row.captured_at), views: numOrNull(row.views) });
+    snapshots.set(key, list);
+  }
+  // Every live post counts once, measured or not, so "N of M" never hides a post that has no reading.
+  const posts = new Map<string, { seriesId: string; platform: string; externalId: string }>();
+  for (const p of live) posts.set(`${p.seriesId}\u0000${p.platform}\u0000${p.externalId}`, p);
+  for (const key of snapshots.keys()) {
+    const [seriesId = "", platform = "", externalId = ""] = key.split("\u0000");
+    if (!posts.has(key)) posts.set(key, { seriesId, platform, externalId });
+  }
+  const groups = new Map<string, { seriesId: string; platform: string; posts: Array<{ externalId: string; gained: number | null; from: string | null; to: string | null; reason: string }> }>();
+  for (const [key, p] of posts) {
+    const g = groups.get(`${p.seriesId}\u0000${p.platform}`) ?? { seriesId: p.seriesId, platform: p.platform, posts: [] };
+    g.posts.push({ externalId: p.externalId, ...viewsGained(snapshots.get(key)) });
+    groups.set(`${p.seriesId}\u0000${p.platform}`, g);
+  }
+  const trends = [...groups.values()]
+    .sort((a, b) => a.seriesId.localeCompare(b.seriesId) || a.platform.localeCompare(b.platform))
+    .map((g) => ({ seriesId: g.seriesId, platform: g.platform, ...summarizeGains(g.posts as never), posts: g.posts }));
+  return { ok: true, trends };
+}

package/src/desk/secrets.ts

@@ -0,0 +1,143 @@
+import { credentialsKey, decryptSecret } from "@vfrey/contracts";
+import type { Account, AppConfig } from "@vfrey/contracts";
+import type { Store } from "../queue/store.js";
+
+export type SecretOwnerKind = "account" | "series";
+
+/** Console columns, per owner. */
+export const SECRET_FIELDS: Record<SecretOwnerKind, string[]> = {
+  account: [
+    "youtubeApiKey",
+    "redditClientId",
+    "redditClientSecret",
+    "tiktokClientKey",
+    "tiktokClientSecret",
+    "metaAppId",
+    "metaAppSecret",
+  ],
+  series: [
+    "googleClientId",
+    "googleClientSecret",
+    "youtubeRefreshToken",
+    "tiktokRefreshToken",
+    "tiktokOpenId",
+    "igUserId",
+    "igAccessToken",
+    "fbPageId",
+    "fbPageToken",
+  ],
+};
+
+/** Account fields land in fixed env names. */
+export const ACCOUNT_SECRET_ENV: Record<string, string> = {
+  youtubeApiKey: "YOUTUBE_API_KEY",
+  redditClientId: "REDDIT_CLIENT_ID",
+  redditClientSecret: "REDDIT_CLIENT_SECRET",
+  tiktokClientKey: "TIKTOK_CLIENT_KEY",
+  tiktokClientSecret: "TIKTOK_CLIENT_SECRET",
+  metaAppId: "META_APP_ID",
+  metaAppSecret: "META_APP_SECRET",
+};
+
+/** Series fields land in the env names the series' platform config names. */
+function seriesSecretEnv(account: Account, field: string): string | null {
+  const { youtube, tiktok, instagram, facebook } = account.platforms;
+  switch (field) {
+    case "googleClientId":
+      return youtube?.clientIdEnv ?? null;
+    case "googleClientSecret":
+      return youtube?.clientSecretEnv ?? null;
+    case "youtubeRefreshToken":
+      return youtube?.refreshTokenEnv ?? null;
+    case "tiktokRefreshToken":
+      return tiktok?.refreshTokenEnv ?? null;
+    case "tiktokOpenId":
+      return tiktok?.openIdEnv ?? null;
+    case "igUserId":
+      return instagram?.igUserIdEnv ?? null;
+    case "igAccessToken":
+      return instagram?.accessTokenEnv ?? null;
+    case "fbPageId":
+      return facebook?.pageIdEnv ?? null;
+    case "fbPageToken":
+      return facebook?.pageTokenEnv ?? null;
+    default:
+      return null;
+  }
+}
+
+export function secretFieldError(ownerKind: string, field: string): { refusal: string; fix: string } | null {
+  if (ownerKind !== "account" && ownerKind !== "series") {
+    return { refusal: `Secret owner ${ownerKind} is not account or series.`, fix: "Use --account <id> or --series <id>." };
+  }
+  if (SECRET_FIELDS[ownerKind].includes(field)) return null;
+  return {
+    refusal: `${field} is not a ${ownerKind} secret field.`,
+    fix: `Use one of: ${SECRET_FIELDS[ownerKind].join(", ")}.`,
+  };
+}
+
+function warnUnreadable(store: Store, accountId: string, ownerKind: string, field: string): void {
+  const message = `The ${ownerKind} secret ${field} could not be decrypted. Set it again with the current CREDENTIALS_KEY.`;
+  const existing = store.db
+    .prepare(`SELECT id FROM desk_warnings WHERE code = 'secret_unreadable' AND message = ? AND acked_at IS NULL LIMIT 1`)
+    .get(message);
+  if (existing) return;
+  store.insertWarning({ accountId, jobId: null, code: "secret_unreadable", message });
+}
+
+/**
+ * Decrypts the desk secrets of one series and its account into env names.
+ * The result is for one job's runtime env. Nothing here touches process.env.
+ */
+export function secretEnvFor(store: Store, account: Account, rawKey: string | undefined): Record<string, string> {
+  const rows = store.db
+    .prepare(
+      `SELECT owner_kind, field, ciphertext FROM desk_secrets
+       WHERE (owner_kind = 'series' AND owner_id = ?)
+          OR (owner_kind = 'account' AND owner_id = (SELECT account_id FROM desk_series WHERE id = ?))`,
+    )
+    .all(account.id, account.id) as Array<{ owner_kind: string; field: string; ciphertext: string }>;
+  if (rows.length === 0) return {};
+  let key: Buffer | null = null;
+  try {
+    key = credentialsKey(rawKey ?? "");
+  } catch {
+    key = null;
+  }
+  const env: Record<string, string> = {};
+  for (const row of rows) {
+    const name = row.owner_kind === "account" ? ACCOUNT_SECRET_ENV[row.field] : seriesSecretEnv(account, row.field);
+    if (!name) continue;
+    try {
+      if (!key) throw new Error("no key");
+      env[name] = decryptSecret(row.ciphertext, key);
+    } catch {
+      warnUnreadable(store, account.id, row.owner_kind, row.field);
+    }
+  }
+  return env;
+}
+
+/** Recomputes the config fields that loadConfig derives from env when a desk secret supplies them. */
+export function configWithSecrets(config: AppConfig, env: Record<string, string>): AppConfig {
+  return {
+    ...config,
+    googleApiKey: env.YOUTUBE_API_KEY ?? config.googleApiKey,
+    reddit: {
+      ...config.reddit,
+      clientId: env.REDDIT_CLIENT_ID ?? config.reddit.clientId,
+      clientSecret: env.REDDIT_CLIENT_SECRET ?? config.reddit.clientSecret,
+    },
+    tiktok: {
+      ...config.tiktok,
+      clientKey: env.TIKTOK_CLIENT_KEY ?? config.tiktok.clientKey,
+      clientSecret: env.TIKTOK_CLIENT_SECRET ?? config.tiktok.clientSecret,
+    },
+    meta: {
+      ...config.meta,
+      appId: env.META_APP_ID ?? config.meta.appId,
+      appSecret: env.META_APP_SECRET ?? config.meta.appSecret,
+    },
+  };
+}

package/src/desk/series.ts

@@ -0,0 +1,127 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { Account } from "@vfrey/contracts";
+import { parseAccounts } from "../config.js";
+import type { Store } from "../queue/store.js";
+import { applyDeskAccount } from "./overlay.js";
+
+const FIRST_RUN_FILE = fileURLToPath(new URL("../../accounts.first-run.json", import.meta.url));
+
+/** Non-secret platform settings that live in desk rows. Env-variable names stay in base_json. */
+const PLATFORM_FIELDS: Record<string, string[]> = {
+  youtube: ["privacyStatus", "categoryId", "madeForKids"],
+  tiktok: ["privacyLevel"],
+  instagram: ["shareToFeed"],
+  facebook: [],
+};
+
+const SOURCE_KINDS = ["rss", "subreddit", "youtubeChannel", "youtubeTrending"] as const;
+
+export function firstRunTemplate(): Account {
+  const [account] = parseAccounts(JSON.parse(readFileSync(FIRST_RUN_FILE, "utf8")) as unknown);
+  if (!account) throw new Error("accounts.first-run.json has no account.");
+  return account;
+}
+
+/** Imports each account that has no desk series yet. Returns the ids it added. */
+export function importAccounts(store: Store, accounts: Account[]): string[] {
+  const added: string[] = [];
+  for (const account of accounts) {
+    const exists = store.db.prepare(`SELECT id FROM desk_series WHERE id = ?`).get(account.id);
+    if (exists) continue;
+    store.db.exec("BEGIN");
+    try {
+      store.db
+        .prepare(`INSERT OR IGNORE INTO desk_accounts (id, name, owner_id, paused) VALUES (?, ?, NULL, 0)`)
+        .run(account.id, account.id);
+      store.createSeries({
+        id: account.id,
+        accountId: account.id,
+        niche: account.niche,
+        language: account.language,
+        timezone: account.cadence.timezone,
+        minHoursBetweenPosts: account.cadence.minHoursBetweenPosts,
+        maxPostsPerDay: account.cadence.maxPostsPerDay,
+        windows: account.cadence.windows,
+        voices: account.voices,
+        hashtagPool: account.hashtagPool,
+        engageEnabled: account.engage.enabled,
+        allowSpicy: account.engage.allowSpicy,
+        maxRepliesPerDay: account.engage.maxRepliesPerDay,
+        minSecondsBetween: account.engage.minSecondsBetweenReplies,
+      });
+      store.db.prepare(`UPDATE desk_series SET base_json = ? WHERE id = ?`).run(JSON.stringify(account), account.id);
+      for (const [platform, config] of Object.entries(account.platforms)) {
+        if (!config) continue;
+        const kept: Record<string, unknown> = {};
+        for (const field of PLATFORM_FIELDS[platform] ?? []) {
+          const value = (config as unknown as Record<string, unknown>)[field];
+          if (value !== undefined) kept[field] = value;
+        }
+        store.setPlatform({ seriesId: account.id, platform, enabled: config.enabled, config: kept });
+      }
+      const sources: Array<[string, string]> = [
+        ...account.sources.rss.map((value): [string, string] => ["rss", value]),
+        ...account.sources.subreddits.map((value): [string, string] => ["subreddit", value]),
+        ...account.sources.youtubeChannelIds.map((value): [string, string] => ["youtubeChannel", value]),
+      ];
+      if (account.sources.youtubeTrendingRegion) sources.push(["youtubeTrending", account.sources.youtubeTrendingRegion]);
+      for (const [kind, value] of sources) store.addSource({ seriesId: account.id, kind, value });
+      store.db.exec("COMMIT");
+      added.push(account.id);
+    } catch (error) {
+      store.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+  return added;
+}
+
+/** Imports the accounts file, then the first-run series when the desk still has none. */
+export function seedDesk(store: Store, accounts: Account[]): void {
+  importAccounts(store, accounts);
+  seedFirstRunIfEmpty(store);
+}
+
+export function seedFirstRunIfEmpty(store: Store): void {
+  if (!deskIsEmpty(store)) return;
+  importAccounts(store, [firstRunTemplate()]);
+}
+
+export function deskIsEmpty(store: Store): boolean {
+  const row = store.db.prepare(`SELECT COUNT(*) AS n FROM desk_series`).get() as { n: number };
+  return Number(row.n) === 0;
+}
+
+/** The series of record, as pipeline accounts. */
+export function deskAccounts(store: Store): Account[] {
+  const rows = store.db.prepare(`SELECT id, niche, language, base_json FROM desk_series ORDER BY id`).all() as Array<{
+    id: string;
+    niche: string;
+    language: string;
+    base_json: string | null;
+  }>;
+  const accounts: Account[] = [];
+  for (const row of rows) {
+    const base: Account = row.base_json
+      ? (JSON.parse(row.base_json) as Account)
+      : { ...firstRunTemplate(), id: row.id, niche: row.niche, language: row.language };
+    const sources = store.db.prepare(`SELECT kind, value FROM desk_sources WHERE series_id = ? ORDER BY rowid`).all(row.id) as Array<{
+      kind: string;
+      value: string;
+    }>;
+    const pick = (kind: (typeof SOURCE_KINDS)[number]) => sources.filter((item) => item.kind === kind).map((item) => item.value);
+    const overlay = store.deskOverlay(row.id);
+    const withDesk = overlay ? applyDeskAccount(base, overlay) : base;
+    accounts.push({
+      ...withDesk,
+      sources: {
+        rss: pick("rss"),
+        subreddits: pick("subreddit"),
+        youtubeChannelIds: pick("youtubeChannel"),
+        youtubeTrendingRegion: pick("youtubeTrending")[0] ?? null,
+      },
+    });
+  }
+  return accounts;
+}

package/src/desk/state.ts

@@ -0,0 +1,77 @@
+import os from "node:os";
+import path from "node:path";
+import { redact } from "../queue/seal.js";
+import type { Store } from "../queue/store.js";
+import { engineById, allEngineStatuses, DEFAULT_ENGINE, type EngineProbes } from "../product/engines.js";
+import { readInsights } from "../product/insights.js";
+import { channelInfo } from "./channel.js";
+import { SECRET_FIELDS } from "./secrets.js";
+import type { TickStatus } from "./tick-runner.js";
+
+export interface StateInput {
+  store: Store;
+  dataDir: string;
+  env: Record<string, string | undefined>;
+  userId: string;
+  tick: TickStatus;
+  probes: EngineProbes;
+  /** The project this desk belongs to, or null for the machine desk (and for an env-chosen data folder). */
+  project?: { id: string; name: string } | null;
+}
+
+/** The path with the user's home folder written as ~. */
+export function shortHome(dir: string, home: string): string {
+  if (home && (dir === home || dir.startsWith(home + path.sep))) return "~" + dir.slice(home.length);
+  return dir;
+}
+
+/** The full `State` of the desk API. Reads only. */
+export async function buildState(input: StateInput): Promise<Record<string, unknown>> {
+  const snapshot = input.store.snapshot(input.userId);
+  let insights: Awaited<ReturnType<typeof readInsights>> = [];
+  try {
+    insights = await readInsights(path.join(input.dataDir, "product", "insights.json"));
+  } catch {
+    insights = [];
+  }
+  return {
+    ok: true,
+    generatedAt: new Date().toISOString(),
+    home: input.dataDir,
+    // Who this server serves. `vfrey open`, `dashboard` and the tick summary match on it to reuse a dashboard.
+    dataDir: input.dataDir,
+    project: input.project ? { id: input.project.id, name: input.project.name } : null,
+    homeDisplay: shortHome(input.dataDir, input.env.HOME || os.homedir()),
+    appEnv: input.env.APP_ENV === "production" ? "production" : "qa",
+    ...snapshot,
+    tick: input.tick,
+    // Public channel and page ids on file, shown so the person can type one to go live. Never a token.
+    channelIds: Object.fromEntries(
+      ((snapshot.series as Array<{ id: string }>) ?? []).map((item) => [
+        item.id,
+        Object.fromEntries(channelInfo(input.store, item.id, input.env.CREDENTIALS_KEY).map((c) => [c.platform, c.id])),
+      ]),
+    ),
+    secretFields: { account: [...SECRET_FIELDS.account], series: [...SECRET_FIELDS.series] },
+    defaultEngine: defaultEngine(input.store),
+    engines: allEngineStatuses(input.probes).map((row) => ({ id: row.id, label: row.label, availability: row.availability, reason: row.reason, note: row.note })),
+    insights: insights.map((row) => ({
+      engineLabel: redact(row.engineLabel),
+      outputPath: row.outputPath,
+      bytes: row.bytes,
+      createdAt: row.createdAt,
+      ...(row.subject !== undefined ? { subject: redact(row.subject) } : {}),
+      ...(row.composition !== undefined ? { composition: row.composition } : {}),
+      ...(row.durationSec !== undefined ? { durationSec: row.durationSec } : {}),
+    })),
+  };
+}
+
+/** The machine default, as a known engine id. */
+function defaultEngine(store: Store): string {
+  try {
+    return engineById(store.engineDefault() ?? DEFAULT_ENGINE).id;
+  } catch {
+    return DEFAULT_ENGINE;
+  }
+}

package/src/desk/studio-route.ts

@@ -0,0 +1,119 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { SceneError } from "../scene/scene.js";
+import { prepareEditCopy, startStudio, type StartStudioInput, type StudioHandle } from "../scene/studio.js";
+import type { Store } from "../queue/store.js";
+
+const ID = /^[A-Za-z0-9-]{1,64}$/;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+export interface StudioRouteOptions {
+  store: Store;
+  dataDir: string;
+  env: Record<string, string | undefined>;
+  project: { id: string; name: string } | null;
+  /** Studios this dashboard started, by scene folder. They stop with the dashboard. */
+  running: Map<string, StudioHandle>;
+  /** Starts a studio. Tests inject a fake. */
+  start?: (input: StartStudioInput) => Promise<StudioHandle>;
+}
+
+export type StudioReply = { status: number; body: Record<string, unknown> };
+
+const refusal = (status: number, message: string, fix: string, code?: string): StudioReply => ({ status, body: { ok: false, refusal: message, fix, ...(code ? { code } : {}) } });
+
+function isDir(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** The folder that holds a project's own scenes (`<project>/scenes`), or the data directory's `scenes` without a project. */
+export function scenesRootFor(options: Pick<StudioRouteOptions, "dataDir" | "project">): string {
+  return options.project ? path.join(path.dirname(options.dataDir), "scenes") : path.join(options.dataDir, "scenes");
+}
+
+async function open(options: StudioRouteOptions, input: StartStudioInput): Promise<StudioHandle> {
+  const known = options.running.get(input.dir);
+  if (known) return known;
+  const handle = await (options.start ?? startStudio)({ ...input, env: options.env });
+  options.running.set(input.dir, handle);
+  return handle;
+}
+
+const rendering = (dir: string) => `Render it as usual: npx vfrey render --scene ${dir} --engine vfrey-framey`;
+
+/**
+ * `POST /api/studio` with `{ run }` or `{ scene }`. A run's stored scene is never opened: it is copied to the project's
+ * `scenes/<name>-edit/` first (kept when it is already there, so earlier edits survive), with the run's timing and voice
+ * supplied. A scene named by `scene` is a folder of the project's own and is edited where it is.
+ */
+export async function studioRoute(options: StudioRouteOptions, body: Record<string, unknown>): Promise<StudioReply> {
+  const runId = typeof body.run === "string" ? body.run : null;
+  const sceneName = typeof body.scene === "string" ? body.scene : null;
+  try {
+    if (runId) {
+      if (!ID.test(runId)) return refusal(404, "No run has that id.", "Open a run from the Runs list.");
+      const row = options.store.db.prepare(`SELECT payload FROM jobs WHERE id = ?`).get(runId) as { payload: string } | undefined;
+      if (!row) return refusal(404, "No run has that id.", "Open a run from the Runs list.");
+      let payload: {
+        scene?: { source?: string; dir?: string | null; kind?: string | null } | null;
+        content?: { title?: string; voiceoverScript?: string; voiceoverPath?: string | null; beats?: Array<{ role?: string; text?: string; caption?: string }> } | null;
+      };
+      try {
+        payload = JSON.parse(row.payload);
+      } catch {
+        return refusal(404, "That run has no scene.", "Open a run that has an agent-written scene.");
+      }
+      const scene = payload.scene;
+      if (!scene || scene.source !== "agent" || !scene.dir) return refusal(404, "That run used the default template, so there is no scene to edit.", "Write a scene (`npx vfrey scene init DIR`) and run with --scene DIR.");
+      if (scene.kind !== "html") {
+        return refusal(409, "The studio edits HTML scenes. This is a Remotion scene (index.tsx).", "edit index.tsx in your own editor, or write an HTML scene to use the studio.", "scene_studio_remotion");
+      }
+      if (!isDir(scene.dir)) return refusal(404, "The run's stored scene copy is no longer on this machine.", "Run it again, or open a scene from the project's scenes folder.");
+      const content = payload.content ?? {};
+      const root = options.project ? path.dirname(options.dataDir) : options.dataDir;
+      const voice = typeof content.voiceoverPath === "string" && content.voiceoverPath ? path.resolve(root, content.voiceoverPath) : null;
+      const copy = await prepareEditCopy({ storedDir: scene.dir, scenesRoot: scenesRootFor(options), name: path.basename(scene.dir) });
+      const handle = await open(options, {
+        dir: copy.dir,
+        supply: {
+          title: content.title ?? "",
+          lines: String(content.voiceoverScript ?? "").split("\n").map((line) => line.trim()).filter(Boolean),
+          beats: (content.beats ?? []).map((b) => ({ role: String(b.role ?? ""), text: String(b.text ?? ""), caption: String(b.caption ?? "") })),
+          voiceFile: voice && existsSync(voice) ? voice : null,
+        },
+      });
+      const message = copy.copied
+        ? `Opened a copy of this run's scene at ${copy.dir}. Your edits are saved there; the run's stored copy is not changed. ${rendering(copy.dir)}`
+        : `Opened your earlier edit copy at ${copy.dir} (the run's stored copy is not changed). ${rendering(copy.dir)}`;
+      return { status: 200, body: { ok: true, url: handle.url, dir: copy.dir, copied: copy.copied, message, warnings: copy.warnings } };
+    }
+    if (sceneName) {
+      if (!options.project) return refusal(404, "This dashboard has no project, so it has no scenes folder.", "Open the dashboard of a project (`npx vfrey open` inside it).");
+      if (!NAME.test(sceneName)) return refusal(404, "No scene has that name.", "Use a folder name from the project's scenes folder.");
+      const dir = path.join(scenesRootFor(options), sceneName);
+      if (!isDir(dir) || !existsSync(path.join(dir, "index.html"))) {
+        const remotion = existsSync(path.join(dir, "index.tsx"));
+        return remotion
+          ? refusal(409, "The studio edits HTML scenes. This is a Remotion scene (index.tsx).", "edit index.tsx in your own editor, or write an HTML scene to use the studio.", "scene_studio_remotion")
+          : refusal(404, "No HTML scene has that name in this project's scenes folder.", "Check the name against the project's scenes folder.");
+      }
+      const handle = await open(options, { dir });
+      return { status: 200, body: { ok: true, url: handle.url, dir, copied: false, message: `Opened ${dir}. Edits are saved there. ${rendering(dir)}`, warnings: [] } };
+    }
+    return refusal(400, "Say which scene to edit.", "Send { run: <run id> } or { scene: <name> }.");
+  } catch (error) {
+    if (error instanceof SceneError) return refusal(409, error.message, error.fix, error.code);
+    throw error;
+  }
+}
+
+/** Stops every studio the dashboard started. */
+export async function closeStudios(running: Map<string, StudioHandle>): Promise<void> {
+  const all = [...running.values()];
+  running.clear();
+  await Promise.allSettled(all.map((studio) => studio.close()));
+}