ossclip 0.1.30 → 0.1.33

package/src/edit.ts

@@ -19,7 +19,11 @@ import {
   ThumbnailConceptSchema,
   approvedOverlayText,
   buildThumbnailPrompt,
+  captionForProvider,
+  createPostizProvider,
+  alignRestamp,
   emptyOverrideDoc,
+  extractAudioSpan,
   // Static import is fine here: the @google/genai SDK load is LAZY inside
   // this function (core's near-zero-dep rule), so the server pays for it
   // only when a regenerate actually runs.
@@ -30,7 +34,12 @@ import {
   PORTRAIT_MIME_TYPES,
   portraitMimeType,
   readCoverProvenance,
+  runWhisper,
   SegmentSchema,
+  spliceTranscript,
+  TranscriptSchema,
+  whisperPromptFor,
+  wordsInSpan,
   type Segment,
   thumbnailImageCacheName,
   type CoverProvenance,
@@ -60,6 +69,10 @@ import {
   type RecordedCommand,
 } from "./cover";
 import { expandHome } from "./paths";
+// The model-path and implied-language rules, from THE source doctor, setup and
+// produce all resolve through — a second copy here would send a user to a
+// model file the rest of the tool never looks for.
+import { modelImpliedLanguage, whisperModelPath } from "./setup/manifest";
 import {
   PORTRAIT_OVERRIDE_BASENAME,
   portraitExtensionForMime,
@@ -68,6 +81,7 @@ import {
   type ResolvedPortrait,
 } from "./portrait-override";
 import { lastFlagValue, thumbnailPanelState } from "./thumbnail-panel";
+import { buildPublishPosts, publishConfigured, publishReceiptPath, readPublishReceipt } from "./publish";
 
 /**
  * Where the built editor page lives (R18 §90b): `editor-dist/` inside this
@@ -94,6 +108,78 @@ export function resolveEditorPageDir(): string | null {
   return candidates[0] ?? null;
 }
 
+/**
+ * The config keys `/api/retranscribe-range` needs. Spelled structurally
+ * rather than as `OssclipConfig` so the `loadCfg` seam keeps accepting a test
+ * stub that supplies only what a case is about — the same shape the youtube/
+ * portrait keys above it are declared with.
+ */
+export interface RetranscribeConfig {
+  ffmpegPath?: string;
+  ffprobePath?: string;
+  whisperPath?: string;
+  model?: string;
+  modelDir?: string;
+  language?: unknown;
+  dictionary?: unknown;
+}
+
+/**
+ * How to spawn whisper for a range re-decode, or why we cannot.
+ *
+ * Pure — the `openCommand`/`openInBrowser` split — so the whole
+ * config × missing-binary × malformed-dictionary matrix is testable without
+ * whisper.cpp or a model on the runner.
+ *
+ * FROM THE CONFIG, not from the workdir's `transcript-key.json`, and that is
+ * a knowing limitation: reading the key would mean importing produce.ts,
+ * which statically pulls in @ossclip/renderer AND imports this module back
+ * (a cycle), for a server whose whole point is to start instantly. The
+ * failure when the two disagree is safe and REPORTED rather than silent: a
+ * range re-decoded with a different model produces words that match nothing,
+ * and `alignRestamp` answers "matched none — stamps left as they were".
+ *
+ * The dictionary is validated all-or-nothing, `validDictionary`'s rule
+ * (produce.ts): a hand-edited list with a number in it biases whisper with a
+ * vocabulary the user never reviewed, so the whole key is dropped instead.
+ * Same for `language`: typeof+trim, never truthiness, never coerced.
+ */
+export function retranscribeSettings(
+  cfg: RetranscribeConfig,
+):
+  | {
+      tools: { ffmpegPath: string; ffprobePath: string };
+      whisperPath: string;
+      modelPath: string;
+      language?: string;
+      prompt?: string;
+    }
+  | { error: string } {
+  if (!cfg.ffmpegPath || !cfg.ffprobePath || !cfg.whisperPath || !cfg.model || !cfg.modelDir) {
+    return {
+      error:
+        "ffmpeg or whisper is not configured — run `ossclip doctor` to see what is missing, " +
+        "then `ossclip setup` to install it.",
+    };
+  }
+  const dict = Array.isArray(cfg.dictionary)
+    && cfg.dictionary.length > 0
+    && cfg.dictionary.every((t) => typeof t === "string" && t.trim().length > 0)
+    ? (cfg.dictionary as string[]).map((t) => t.trim())
+    : [];
+  const language = typeof cfg.language === "string" && cfg.language.trim().length > 0
+    ? cfg.language.trim()
+    : modelImpliedLanguage(cfg.model);
+  const prompt = whisperPromptFor(dict);
+  return {
+    tools: { ffmpegPath: cfg.ffmpegPath, ffprobePath: cfg.ffprobePath },
+    whisperPath: cfg.whisperPath,
+    modelPath: whisperModelPath(cfg.model, cfg.modelDir),
+    ...(language !== undefined ? { language } : {}),
+    ...(prompt !== undefined ? { prompt } : {}),
+  };
+}
+
 /**
  * The editor's backend: a handful of endpoints and a static file server,
  * deliberately dependency-free. It reads the workdir a `produce` run left
@@ -158,6 +244,14 @@ const MIME: Record<string, string> = {
   // the type is stated while the change is one line rather than a debugging
   // session.
   ".wav": "audio/wav",
+  // The `--cover-in-video` overlay: produce stages the cover into the workdir
+  // as well as the render's public dir, and the Player fetches it through
+  // `/media/`. Browsers do sniff an image served as octet-stream, but a
+  // preview that depends on sniffing is a preview that breaks the first time
+  // something in front of it (a proxy, a stricter engine) declines to.
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
 };
 
 /**
@@ -254,7 +348,19 @@ export async function startEditServer(
     /** Config seam for the thumbnail panel — tests inject `() => ({})` so a
      * run never reads the runner's real ~/.ossclip/config.json (the
      * `recentDir` rule applied to reads). */
-    loadCfg?: () => { youtube?: unknown; portrait?: unknown; thumbnailModel?: unknown };
+    loadCfg?: () => {
+      youtube?: unknown;
+      portrait?: unknown;
+      thumbnailModel?: unknown;
+      postizUrl?: string;
+    } & RetranscribeConfig;
+    /** Env seam for the publish endpoints — tests inject their own so the
+     * runner's real OSSCLIP_POSTIZ_API_KEY (or its absence) never decides a
+     * test (the loadCfg rule applied to the environment). */
+    publishEnv?: NodeJS.ProcessEnv;
+    /** Fetch seam for the publish endpoints — tests stub Postiz instead of
+     * needing an instance on the runner (createPostizProvider's fetchImpl). */
+    publishFetch?: typeof fetch;
     /** File-manager reveal seam (the `generateThumbnail` pattern) — tests
      * observe the revealed path instead of popping a real Finder/Explorer
      * window on the runner. */
@@ -266,6 +372,14 @@ export async function startEditServer(
      * is also why cover.ts keeps that import lazy in the first place.
      */
     renderCover?: CoverSeams["renderCover"];
+    /**
+     * The two shell-outs `/api/retranscribe-range` makes — the
+     * `generateThumbnail` seam pattern, twice: tests stub a decode instead of
+     * needing ffmpeg, whisper.cpp and a multi-gigabyte model on the runner
+     * (`edit-server.test.ts` must stay a unit test).
+     */
+    sliceAudio?: typeof extractAudioSpan;
+    runWhisper?: typeof runWhisper;
   } = {},
 ): Promise<EditServer> {
   // MUTABLE since R17 §83: the server can start with no project (the page
@@ -355,6 +469,14 @@ export async function startEditServer(
   // headless browser, and a double-click must not run two renders at the same
   // destination. `thumbnailBusy`'s rule, for the same reason.
   let coverBusy = false;
+  /**
+   * One range re-decode at a time (`/api/retranscribe-range`). whisper is a
+   * CPU-bound spawn AND the endpoint read-modify-writes transcript.json, so
+   * two in flight is both a stalled box and a lost splice — the second write
+   * would be built on a transcript read before the first one landed.
+   * `coverBusy`'s rule with a second reason on top.
+   */
+  let retranscribeBusy = false;
   /** Where the JPEG lives right now: the destination the last cover used,
    * else `<recorded out>.cover.jpg`. Existence is the caller's check — a
    * recorded destination that was never rendered is a real state (the panel
@@ -369,6 +491,11 @@ export async function startEditServer(
    * file behind this URL). */
   const coverImageUrl = (image: string | null): string | null =>
     image === null ? null : `/api/cover/image?ts=${Math.round(statSync(image).mtimeMs)}`;
+  /** Where the Preview button's one-off render lands (handoff-cover-panel
+   * §3): a fixed name IN the workdir — never a client-named path, and never
+   * the canonical `.cover.jpg` a real Apply owns. Each preview overwrites the
+   * last; the file is scratch, like the frame-sampler's cache. */
+  const coverPreviewPath = (): string => join(workdir!, "cover-preview.jpg");
 
   // ---- Portrait override (editor face swap, 2026-08-17) -------------------
   // A per-project `portrait-override.<ext>` in the workdir that outranks the
@@ -550,6 +677,157 @@ export async function startEditServer(
           });
         }
 
+        if (url.pathname === "/api/transcript" && req.method === "GET") {
+          // The FULL transcript, source-timed words included (cut-review
+          // rework follow-up): the editor rebuilds the caption track over
+          // REVIVED material with produce's own `buildCaptionLines`, and
+          // render-props' captionLines only cover what the last render kept
+          // — the revived words exist nowhere else client-side. Lenient like
+          // /api/cleanup: a missing or corrupt transcript.json degrades to
+          // null (captions over revived material stay absent, never a 500).
+          if (!workdir) return send(409, { error: "no workdir open" });
+          try {
+            const raw = JSON.parse(await readFile(join(workdir, "transcript.json"), "utf8")) as {
+              language?: unknown;
+              words?: unknown;
+            };
+            if (!Array.isArray(raw.words)) return send(200, { transcript: null });
+            return send(200, { transcript: raw });
+          } catch {
+            return send(200, { transcript: null });
+          }
+        }
+
+        if (url.pathname === "/api/retranscribe-range" && req.method === "POST") {
+          // Re-decode ONE source span and re-stamp the words already there
+          // (Phase A, 2026-08-26): inside a kept retake whisper mis-POSITIONS
+          // words — the caption says "has its" while the audio says "could
+          // read 50 files" — because the first decode ran over material the
+          // cut had removed. See restamp.ts for why the splice is
+          // stamps-only.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          if (retranscribeBusy) {
+            return send(409, { error: "a re-transcription is already running" });
+          }
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          // TWO steerable values, both times, and nothing else — the cover
+          // regenerate rule: unknown keys are stripped by the parse, and an
+          // ordered non-negative pair is checked HERE rather than trusted,
+          // since an inverted range would slice a negative duration out of
+          // ffmpeg (CLAUDE.md's parse-never-coerce).
+          const parsed = z
+            .object({ srcIn: z.number().nonnegative(), srcOut: z.number().nonnegative() })
+            .refine((v) => v.srcOut > v.srcIn, { message: "srcOut must be after srcIn" })
+            .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+          if (!parsed.success) return send(400, { error: parsed.error.message });
+          const { srcIn, srcOut } = parsed.data;
+          // Every path server-derived, never from the body — the regenerate
+          // endpoint's stance. `whisper-range` is a distinct outBase from
+          // produce's `whisper`, so a range decode can never overwrite the
+          // artefact of the full one.
+          const dir = workdir;
+          const tmpWav = join(dir, "whisper-range.wav");
+          const outBase = join(dir, "whisper-range");
+          retranscribeBusy = true;
+          try {
+            const audio = join(dir, "audio.wav");
+            if (!existsSync(audio)) {
+              return send(200, {
+                ok: false,
+                error: "this workdir has no audio.wav to re-decode — re-run `ossclip produce`.",
+              });
+            }
+            const transcriptPath = join(dir, "transcript.json");
+            if (!existsSync(transcriptPath)) {
+              return send(200, {
+                ok: false,
+                error: "this workdir has no transcript.json to re-stamp — re-run `ossclip produce`.",
+              });
+            }
+            const settings = retranscribeSettings((opts.loadCfg ?? loadConfig)());
+            if ("error" in settings) return send(200, { ok: false, error: settings.error });
+            if (!existsSync(settings.modelPath)) {
+              // The `--transcript`-only install: whisper was never needed to
+              // make this project, so say what to run rather than 500ing.
+              return send(200, {
+                ok: false,
+                error:
+                  `whisper model not found at ${settings.modelPath} — run \`ossclip setup\` ` +
+                  `to download it.`,
+              });
+            }
+            // Parsed, not cast: this file is about to be rewritten, and a
+            // truncated one must fail loudly here rather than become the new
+            // transcript.
+            const transcript = TranscriptSchema.parse(
+              JSON.parse(await readFile(transcriptPath, "utf8")),
+            );
+            const range = wordsInSpan(transcript.words, srcIn, srcOut);
+            if (range.to === range.from) {
+              // Silence, or a range whose words all straddle its edges.
+              // Nothing to re-stamp is a SUCCESS with an empty mapping — the
+              // editor's no-op — not a failure the user has to read.
+              return send(200, {
+                ok: true,
+                mapping: [],
+                reports: ["no transcript words lie wholly inside that range"],
+              });
+            }
+            await (opts.sliceAudio ?? extractAudioSpan)(
+              settings.tools,
+              audio,
+              tmpWav,
+              srcIn,
+              srcOut - srcIn,
+            );
+            const fresh = await (opts.runWhisper ?? runWhisper)(
+              {
+                whisperPath: settings.whisperPath,
+                modelPath: settings.modelPath,
+                outBase,
+                ...(settings.language !== undefined ? { language: settings.language } : {}),
+                ...(settings.prompt !== undefined ? { prompt: settings.prompt } : {}),
+              },
+              tmpWav,
+            );
+            const restamped = alignRestamp(
+              transcript.words.slice(range.from, range.to),
+              fresh.words,
+              srcIn,
+            );
+            const next = spliceTranscript(transcript, range, restamped.words);
+            // Atomic, like the overrides write: produce may read this file at
+            // any moment (its cache-reuse branch reads it verbatim and writes
+            // back what it read), and a half-written transcript is worse than
+            // a stale one.
+            const tmp = `${transcriptPath}.tmp`;
+            await writeFile(tmp, JSON.stringify(next, null, 2));
+            await rename(tmp, transcriptPath);
+            // `overrides.json` IS NOT TOUCHED HERE, on purpose: the doc is
+            // client-owned — the editor holds unsaved edits and an undo stack
+            // over it — so the caption RE-KEY rides back as `mapping` and is
+            // applied by the `useEdits` reducer, one commit, one undo step.
+            return send(200, { ok: true, mapping: restamped.mapping, reports: restamped.reports });
+          } catch (err) {
+            // 200 {ok:false}, the cover regenerate posture: a missing whisper
+            // binary or a failed decode is a sentence the panel shows, not a
+            // dead 500 — and the editor keeps working on the old stamps.
+            const message = err instanceof Error ? err.message : String(err);
+            return send(200, {
+              ok: false,
+              error: `${message} — run \`ossclip doctor\` if ffmpeg or whisper is the problem.`,
+            });
+          } finally {
+            retranscribeBusy = false;
+            // Both artefacts are per-request scratch. `.catch()` because a
+            // decode that never got as far as writing one must not turn a
+            // reported failure into an unhandled rejection.
+            await unlink(tmpWav).catch(() => {});
+            await unlink(`${outBase}.json`).catch(() => {});
+          }
+        }
+
         if (url.pathname === "/api/cleanup" && req.method === "GET") {
           // The labeled removals: since cut review step 3 this serves the
           // PROPOSAL (`cutlistProposed` — the automatic cutlist before the
@@ -1180,6 +1458,123 @@ export async function startEditServer(
           return send(200, { ok: true, mdPath });
         }
 
+        // ---- Publish (2026-08-26) -----------------------------------------
+        // The server's FIRST outbound-network endpoints, against the
+        // roadmap's "replay-only by deliberate design" posture — allowed
+        // because all three gates hold: they exist behaviorally only when the
+        // user configured their own Postiz instance (unconfigured → a hint,
+        // never a control), they fire only on an explicit button press, and
+        // the API key never reaches the browser — the server (already running
+        // in the user's shell env) does the upload.
+        if (url.pathname === "/api/publish" && req.method === "GET") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const configured = publishConfigured((opts.loadCfg ?? loadConfig)(), opts.publishEnv ?? process.env);
+          if (!configured.ok) {
+            return send(200, { configured: false, reason: configured.message });
+          }
+          const cmd = await readCommandRecord();
+          const out = cmd ? recordedOutPath(cmd) : null;
+          const pack = await currentYoutubePack();
+          let integrations: Array<{ id: string; provider: string; name: string; caption: string }> = [];
+          try {
+            const provider = createPostizProvider({
+              baseUrl: configured.baseUrl,
+              apiKey: configured.apiKey,
+              fetchImpl: opts.publishFetch,
+            });
+            const targets = await provider.listTargets();
+            integrations = targets.map((t) => ({
+              ...t,
+              // The caption the publish WOULD use — authored-else-derived —
+              // so the panel previews truth, not a guess of it.
+              caption: pack !== null ? captionForProvider(pack, t.provider) : "",
+            }));
+          } catch (err) {
+            return send(200, {
+              configured: true,
+              reachable: false,
+              reason: err instanceof Error ? err.message : String(err),
+            });
+          }
+          return send(200, {
+            configured: true,
+            reachable: true,
+            integrations,
+            packAvailable: pack !== null,
+            outPathExists: out !== null && existsSync(out),
+            receipt: await readPublishReceipt(workdir),
+          });
+        }
+
+        if (url.pathname === "/api/publish" && req.method === "POST") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const configured = publishConfigured((opts.loadCfg ?? loadConfig)(), opts.publishEnv ?? process.env);
+          if (!configured.ok) return send(412, { error: configured.message });
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          const parsed = z
+            .object({
+              integrationIds: z.array(z.string()).min(1),
+              // ISO-8601, validated as a real FUTURE instant below — zod can
+              // say "string", only a clock can say "future".
+              at: z.string().optional(),
+              // Per-integration caption overrides typed in the panel; absent
+              // ids fall back to the pack's authored-else-derived caption.
+              captions: z.record(z.string(), z.string()).optional(),
+              force: z.boolean().optional(),
+            })
+            .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+          if (!parsed.success) return send(400, { error: parsed.error.message });
+          let when: { kind: "now" } | { kind: "at"; iso: string } = { kind: "now" };
+          if (parsed.data.at !== undefined) {
+            const ms = Date.parse(parsed.data.at);
+            if (Number.isNaN(ms)) return send(400, { error: `not an ISO-8601 time: "${parsed.data.at}"` });
+            if (ms <= Date.now()) return send(400, { error: `schedule time already passed: "${parsed.data.at}"` });
+            when = { kind: "at", iso: new Date(ms).toISOString() };
+          }
+          const cmd = await readCommandRecord();
+          const out = cmd ? recordedOutPath(cmd) : null;
+          if (out === null || !existsSync(out)) {
+            return send(412, { error: "no finished render to publish — render first" });
+          }
+          const pack = await currentYoutubePack();
+          if (pack === null) {
+            return send(412, { error: "no YouTube pack — approve one in the SEO panel first" });
+          }
+          const receipt = await readPublishReceipt(workdir);
+          if (receipt !== null && parsed.data.force !== true) {
+            return send(412, {
+              error: `already published on ${receipt.publishedAt} — pass force to publish again`,
+              receipt,
+            });
+          }
+          try {
+            const provider = createPostizProvider({
+              baseUrl: configured.baseUrl,
+              apiKey: configured.apiKey,
+              fetchImpl: opts.publishFetch,
+            });
+            const targets = await provider.listTargets();
+            const picked = parsed.data.integrationIds.map((id) => {
+              const hit = targets.find((t) => t.id === id);
+              if (!hit) throw new Error(`no integration with id "${id}" in Postiz`);
+              return hit;
+            });
+            const posts = buildPublishPosts(pack, picked).map((p) => ({
+              ...p,
+              caption: parsed.data.captions?.[p.target.id] ?? p.caption,
+            }));
+            const result = await provider.publish({ videoPath: out, posts, when });
+            await writeFile(publishReceiptPath(workdir), `${JSON.stringify(result, null, 2)}\n`);
+            return send(200, { ok: true, receipt: result });
+          } catch (err) {
+            // Fail loud, verbatim — Postiz's own validation message is the
+            // most specific thing anyone has (per-provider settings are its
+            // domain, not ours).
+            return send(502, { error: err instanceof Error ? err.message : String(err) });
+          }
+        }
+
         if (url.pathname === "/api/cover" && req.method === "GET") {
           // The cover panel's one status call (2026-08-19): the provenance to
           // prefill and where the current image is. All reads — the panel
@@ -1193,6 +1588,27 @@ export async function startEditServer(
           // throw for want of a destination, and the panel says so up front
           // rather than after a click.
           const outPath = provenance?.out ?? (await recordedArtifactPath(".cover.jpg"));
+          // The finished mp4's OWN span set — the RESOLVED cutlist, never the
+          // proposal /api/cleanup serves: the panel converts the playhead
+          // between the output clock and the source clock
+          // (handoff-cover-panel §1), and a proposal the user's vetoes already
+          // changed is the wrong ruler. Lenient per-span parse, [] on a
+          // missing or corrupt production.json — a cover panel that cannot
+          // convert must still open.
+          let coverCutlist: Segment[] = [];
+          try {
+            const production = JSON.parse(
+              await readFile(join(workdir, "production.json"), "utf8"),
+            ) as { cutlist?: unknown };
+            if (Array.isArray(production.cutlist)) {
+              coverCutlist = production.cutlist.flatMap((s) => {
+                const p = SegmentSchema.safeParse(s);
+                return p.success ? [p.data] : [];
+              });
+            }
+          } catch {
+            // degrade — same as /api/cleanup
+          }
           return send(200, {
             status: outPath === null ? "unavailable" : "ready",
             ...(outPath === null
@@ -1203,6 +1619,7 @@ export async function startEditServer(
             provenance,
             outPath,
             imageUrl: coverImageUrl(image),
+            cutlist: coverCutlist,
           });
         }
 
@@ -1283,6 +1700,78 @@ export async function startEditServer(
           }
         }
 
+        if (url.pathname === "/api/cover/preview-image" && req.method === "GET") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const image = coverPreviewPath();
+          if (!existsSync(image)) return send(404, { error: "no preview image" });
+          // /api/cover/image's exact posture, for its exact reason: every
+          // preview REPLACES the file behind a URL the panel busts with ?ts,
+          // and a cached 200 would show the old preview against the new ts.
+          const bytes = await readFile(image);
+          res.writeHead(200, {
+            "content-type": "image/jpeg",
+            "cache-control": "no-store",
+            "content-length": String(bytes.length),
+          });
+          res.end(bytes);
+          return;
+        }
+
+        if (url.pathname === "/api/cover/preview" && req.method === "POST") {
+          // The regenerate handler above, verbatim, up to the outPath: a
+          // preview is a full cover render — it boots the same headless
+          // browser (hence the same coverBusy gate), takes the same three
+          // steerable values and nothing else, and fails with the same
+          // 200-with-ok:false verbatim-message posture.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          if (coverBusy) return send(409, { error: "a cover regeneration is already running" });
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          const parsed = z
+            .object({
+              text: z.string().optional(),
+              atSec: CoverAtSecondsSchema.optional(),
+              from: CoverFromSchema.optional(),
+            })
+            .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+          if (!parsed.success) return send(400, { error: parsed.error.message });
+          coverBusy = true;
+          try {
+            const notes: string[] = [];
+            await regenerateCover(
+              workdir,
+              {
+                text: parsed.data.text,
+                atSec: parsed.data.atSec,
+                from: parsed.data.from,
+                // The ONE-OFF path, derived HERE and never from the body (the
+                // regenerate handler's comment owns why). Same machinery as
+                // `ossclip cover --out` (handoff-cover-panel §3): the
+                // canonical cover is untouched, provenance updates to
+                // describe the previewed frame — which is what makes a
+                // follow-up blank-field Apply adopt it via the cheap path,
+                // and the one-off note riding back is the panel's disclosure
+                // of exactly that.
+                outPath: coverPreviewPath(),
+              },
+              { renderCover: opts.renderCover, log: (line) => notes.push(line) },
+            );
+            return send(200, {
+              ok: true,
+              notes,
+              // coverImageUrl's mtime rule, aimed at the preview file: the
+              // URL changes exactly when the file does.
+              previewImageUrl: `/api/cover/preview-image?ts=${Math.round(
+                statSync(coverPreviewPath()).mtimeMs,
+              )}`,
+            });
+          } catch (err) {
+            return send(200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+          } finally {
+            coverBusy = false;
+          }
+        }
+
         if (url.pathname.startsWith("/media/")) {
           if (!workdir) return send(409, { error: "no workdir open" });
           const file = join(workdir, decodeURIComponent(url.pathname.slice("/media/".length)));