ossclip 0.1.23 → 0.1.25

package/src/interactive/produce-wizard.ts

@@ -1,19 +1,27 @@
-import { basename } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import { existsSync, readdirSync } from "node:fs";
+import { saveConfigPatch, type OssclipConfig } from "@ossclip/core";
+import { MODELS, bareWhisperModelName, modelImpliedLanguage } from "../setup/manifest";
+import { defaultOutPath } from "../produce";
+import { expandHome } from "../paths";
 import { askInput } from "./ask-input";
+import { pickSavePath } from "./pick-save-path";
 import { produceArgv, type ProduceAnswers, type ProduceExtras } from "./produce-argv";
 import { assertInteractive, confirm, intro, multiselect, select, text, unwrap } from "./prompts";
 
 /**
- * The produce wizard. Thirty-four flags (plus the positional input path)
+ * The produce wizard. Forty-one flags (plus the positional input path)
  * sorted into three tiers: six prompts asked directly — the input path, plus
- * five flags (--out, --cleanup, --aspect, --produce, --intent) — ten behind
- * one "anything else?" multiselect, and the remaining stay flags-only:
+ * five flags (--out, --cleanup, --aspect, --produce, --intent) — eleven
+ * behind one "anything else?" multiselect, and the remaining stay flags-only:
  * debug/internal surfaces, replay-only fields, --no-watermark (the
  * multiselect only turns the credit ON; off is already the default),
+ * --no-youtube (the same shape: the pack entry only turns it ON),
  * --captions (the mirror case: ON is already the default, so the
  * multiselect entry is the OFF switch and the positive flag exists only for
- * replay pinning), or
+ * replay pinning), --add-jump-cuts (same mirror: auto already punches, the
+ * multiselect entry is the OFF switch, and the force flag exists to beat a
+ * future config-off), or
  * (final-review fix wave, Finding 1) --sort. A folder's clip order only means anything once the
  * folder has been enumerated, and that enumeration happens inside
  * `produce()` — after the wizard has already returned argv — so there is
@@ -32,15 +40,23 @@ const EXTRAS = [
   { value: "sourceFit", label: "Show the whole frame instead of cropping", hint: "--source-fit contain" },
   { value: "speaker", label: "Say who is on camera", hint: "--speaker" },
   { value: "whisperModel", label: "Pick a transcription model", hint: "--whisper-model" },
+  // Retake collapse is deliberately NOT an entry (2026-08-16): it runs
+  // automatically with --blooper-marker and never otherwise
+  // (inferredRetakesEnabled, produce.ts), and the user asked for it not to
+  // be exposed as its own knob — the marker entry above IS the switch.
   { value: "blooperMarker", label: "Cut flubbed takes on a spoken word", hint: "--blooper-marker" },
-  {
-    value: "collapseRetakes",
-    label: "Collapse repeated takes automatically",
-    hint: "--collapse-retakes",
-  },
   { value: "sourceIsEdited", label: "Source already has burned-in text", hint: "--source-is-edited" },
   { value: "captionsOff", label: "Turn the burned-in captions off", hint: "--no-captions" },
+  { value: "jumpCutsOff", label: "No punch-in zooms at cuts", hint: "--no-jump-cuts" },
   { value: "watermark", label: 'Credit the tool with a small "made with ossclip"', hint: "--watermark" },
+  // The hint says the approval part out loud (thumbnail UX, 2026-08-16):
+  // ticking this adds an interactive stop before the render, and a surprise
+  // prompt mid-run reads as a hang to someone who didn't expect it.
+  {
+    value: "youtube",
+    label: "YouTube pack: SEO metadata + AI thumbnail",
+    hint: "--youtube · you approve the thumbnail concept before render",
+  },
   { value: "llm", label: "Choose the LLM provider", hint: "--llm" },
 ] as const;
 
@@ -74,22 +90,78 @@ export function extrasFor(
   );
 }
 
-/** Select value that routes to the free-text model prompt instead of a name. */
-export const CUSTOM_MODEL = "__custom__";
+/**
+ * Which follow-up prompts the youtube extra asks, given what the config
+ * already supplies — `watermarkFromConfig`'s gating idea applied to the
+ * follow-up tier: a question whose answer is already in
+ * ~/.ossclip/config.json is noise, not a prompt (the flag still overrides
+ * the config for a one-off; that is a typed-flags surface, not a wizard
+ * one). `typeof`+trim, not truthiness: config.json is hand-edited and
+ * unparsed, and a `"audience": true` typo must mean "still ask", never a
+ * skipped question over a bogus value. Pure so the gating matrix is
+ * testable without a TTY.
+ */
+export function youtubeFollowups(cfg: {
+  audience?: string;
+  portrait?: string;
+  thumbnailBrief?: string;
+}): Array<"audience" | "portrait" | "brief"> {
+  const asks: Array<"audience" | "portrait" | "brief"> = [];
+  if (typeof cfg.audience !== "string" || cfg.audience.trim() === "") asks.push("audience");
+  if (typeof cfg.portrait !== "string" || cfg.portrait.trim() === "") asks.push("portrait");
+  if (typeof cfg.thumbnailBrief !== "string" || cfg.thumbnailBrief.trim() === "") {
+    asks.push("brief");
+  }
+  return asks;
+}
 
 /**
- * A model pick reduced to its bare name: basename, minus the optional ggml-
- * prefix and .bin suffix. Exists because the language prefill classifies on
- * `.endsWith(".en")`, and an absolute path like /x/ggml-small.en.bin ends in
- * ".bin" — an English model would have been prefilled `auto` (review fix,
- * Urdu field test 2026-08-05).
+ * The config patch a yes to "remember these for future runs?" writes, or
+ * null when nothing was freshly typed — null means the offer never appears.
+ * Only answers TYPED into this run's follow-ups qualify: a key the config
+ * already supplies was never asked (youtubeFollowups gates the prompts on
+ * exactly that), and the same gate here keeps a future re-ask from letting a
+ * wizard answer silently clobber a hand-edited config.json. Portrait is
+ * stored as the expandHome-expanded absolute path — a `~` string in
+ * config.json would work today (produce.ts expands the config value too, see
+ * its own comment at the thumbnail step), but an absolute path in a
+ * hand-edited file is self-documenting about which home it meant. Pure, with
+ * `home` injectable like expandHome's own, so the matrix is testable without
+ * a TTY or the real homedir.
+ *
+ * Wizard-only by placement: flag-driven runs never reach this — power users
+ * have config, and an interactive prompt at the end of a scripted run would
+ * break the script.
  */
-export function bareWhisperModelName(nameOrPath: string): string {
-  const base = basename(nameOrPath);
-  const m = /^(?:ggml-)?(.+?)(?:\.bin)?$/.exec(base);
-  return m?.[1] ?? base;
+export function rememberPatch(
+  typed: { audience?: string; portrait?: string; thumbnailBrief?: string },
+  cfg: { audience?: string; portrait?: string; thumbnailBrief?: string },
+  home?: string,
+): Partial<OssclipConfig> | null {
+  const asked = new Set(youtubeFollowups(cfg));
+  // Same typeof+trim rule as youtubeFollowups: a whitespace answer was
+  // already dropped by the prompts, but a durable config write deserves the
+  // same parse-don't-coerce guard as the read side.
+  const fresh = (v: string | undefined): v is string =>
+    typeof v === "string" && v.trim() !== "";
+  const patch: Partial<OssclipConfig> = {};
+  if (asked.has("audience") && fresh(typed.audience)) patch.audience = typed.audience;
+  if (asked.has("portrait") && fresh(typed.portrait)) {
+    patch.portrait = resolve(expandHome(typed.portrait, home));
+  }
+  if (asked.has("brief") && fresh(typed.thumbnailBrief)) {
+    patch.thumbnailBrief = typed.thumbnailBrief;
+  }
+  return Object.keys(patch).length === 0 ? null : patch;
 }
 
+/** Select value that routes to the free-text model prompt instead of a name. */
+export const CUSTOM_MODEL = "__custom__";
+
+// Moved to the setup manifest (its language/URL tables need the same
+// stripping); re-exported so this module's callers and tests keep one home.
+export { bareWhisperModelName };
+
 /** The three names `ossclip setup` knows how to download, with their hints. */
 const CANONICAL_MODELS = [
   { value: "base.en", hint: "fastest, least accurate" },
@@ -123,8 +195,24 @@ export function whisperModelChoices(
     label: c.value,
     hint: installed.has(c.value) ? c.hint : `${c.hint} · will need download`,
   }));
-  const canonical = new Set<string>(CANONICAL_MODELS.map((c) => c.value));
-  for (const name of [...installed].filter((n) => !canonical.has(n)).sort()) {
+  // Curated fine-tunes (a manifest `url` marks one): listed like the
+  // canonicals whether or not downloaded — setup can fetch them now, so the
+  // wizard must be able to name them (the one-command experience the curated
+  // table exists for), with the provenance note as the hint.
+  const curated = Object.entries(MODELS).filter(
+    ([name, info]) => info.url !== undefined && !CANONICAL_MODELS.some((c) => c.value === name),
+  );
+  for (const [name, info] of curated) {
+    choices.push({
+      value: name,
+      label: name,
+      hint:
+        (info.note ?? "curated fine-tune") +
+        (installed.has(name) ? "" : " · will need download"),
+    });
+  }
+  const listed = new Set(choices.map((c) => c.value));
+  for (const name of [...installed].filter((n) => !listed.has(n)).sort()) {
     choices.push({ value: name, label: name, hint: "installed" });
   }
   choices.push({
@@ -135,8 +223,30 @@ export function whisperModelChoices(
   return choices;
 }
 
+/**
+ * The language follow-up's prefill for a picked model. The curated table's
+ * own language wins — `medium-urdu` prefills `ur`, so plain Enter runs the
+ * fine-tune with the code it was trained for instead of the `auto` detect
+ * gamble. Otherwise the standing heuristic: a non-.en pick is multilingual
+ * by construction, so `auto` lets whisper detect; `.en` keeps whisper's en
+ * default (empty = no flag, produceArgv's default-elision rule).
+ */
+export function whisperLanguagePrefill(model: string): string {
+  return modelImpliedLanguage(model) ?? (bareWhisperModelName(model).endsWith(".en") ? "" : "auto");
+}
+
 export async function produceWizard(
-  cfg: { speaker?: string; modelDir?: string; input?: string; watermark?: boolean } = {},
+  cfg: {
+    speaker?: string;
+    modelDir?: string;
+    input?: string;
+    watermark?: boolean;
+    /** Gate the youtube follow-ups (youtubeFollowups): ask only what the
+     * config doesn't already answer. */
+    audience?: string;
+    portrait?: string;
+    thumbnailBrief?: string;
+  } = {},
 ): Promise<string[]> {
   assertInteractive("produce wizard");
   intro("ossclip produce");
@@ -190,10 +300,18 @@ export async function produceWizard(
       ) as string)
     : undefined;
 
-  const defaultOut = `${basename(input).replace(/\.[^.]+$/, "")}.ossclip.mp4`;
-  const out = unwrap(
-    await text({ message: "Output file", placeholder: defaultOut, defaultValue: "" }),
-  ) as string;
+  // Folder walk instead of the raw text prompt (2026-08-16 `~`-path
+  // incident, pick-save-path.ts). The default name comes from produce's own
+  // `defaultOutPath`, not this file's old duplicate regex, so the fast-path
+  // row names exactly the file a flag-less run writes; picking that row
+  // returns undefined and the elision rule below emits no --out at all.
+  // Resolved first because a typed relative input must anchor the walk (and
+  // the default's folder) to cwd, not to wherever `dirname` lands.
+  const resolvedInput = resolve(input);
+  const out = await pickSavePath({
+    startDir: dirname(resolvedInput),
+    defaultName: basename(defaultOutPath(resolvedInput)),
+  });
 
   const chosen = unwrap(
     await multiselect({
@@ -221,12 +339,93 @@ export async function produceWizard(
     );
   }
   if (chosen.includes("sourceFit")) extras.sourceFit = "contain";
-  if (chosen.includes("collapseRetakes")) extras.collapseRetakes = true;
   if (chosen.includes("sourceIsEdited")) extras.sourceIsEdited = true;
   // The entry is the OFF switch (captions default ON — see EXTRAS), so a
   // tick maps to `captions: false` and produceArgv emits `--no-captions`.
   if (chosen.includes("captionsOff")) extras.captions = false;
+  // Same OFF-switch shape (the punch defaults ON, face-only): a tick maps
+  // to `jumpCuts: false` and produceArgv emits `--no-jump-cuts`.
+  if (chosen.includes("jumpCutsOff")) extras.jumpCuts = false;
   if (chosen.includes("watermark")) extras.watermark = true;
+  if (chosen.includes("youtube")) {
+    extras.youtube = true;
+    // Follow-ups under the same extra, like --clip's seconds prompt — but
+    // gated on the config (youtubeFollowups): a question whose answer is
+    // already in ~/.ossclip/config.json is never re-asked. All three trim,
+    // like the language follow-up: a whitespace answer must not become a
+    // bogus flag value, and an empty answer means "no flag" (the config, or
+    // nothing, decides).
+    const followups = youtubeFollowups(cfg);
+    if (followups.includes("audience")) {
+      const audience = (
+        unwrap(
+          await text({
+            message: "Who is this channel for?",
+            placeholder: "junior web devs learning AI tooling",
+            defaultValue: "",
+          }),
+        ) as string
+      ).trim();
+      if (audience) extras.audience = audience;
+    }
+    if (followups.includes("portrait")) {
+      // The portrait only means anything to the pack's AI thumbnail.
+      // Optional — empty skips the flag, and the thumbnail falls back to
+      // the frame-grab cover.
+      const portrait = (
+        unwrap(
+          await text({
+            message: "Portrait photo for the AI thumbnail (empty = use the frame-grab cover)",
+            placeholder: "~/Pictures/me.jpg",
+            defaultValue: "",
+          }),
+        ) as string
+      ).trim();
+      if (portrait) extras.portrait = portrait;
+    }
+    if (followups.includes("brief")) {
+      const brief = (
+        unwrap(
+          await text({
+            message: "Anything the thumbnail must get right? (optional)",
+            placeholder: "always show the terminal, never stock imagery",
+            defaultValue: "",
+          }),
+        ) as string
+      ).trim();
+      if (brief) extras.thumbnailBrief = brief;
+    }
+    // Offer to persist the fresh answers (UX completion, 2026-08-17): all
+    // three are durable channel facts, and before this the wizard re-asked
+    // them every run until the user hand-edited ~/.ossclip/config.json. The
+    // write is an ADDITION for the NEXT run (loadConfig picks it up), never a
+    // substitute for the flags: this run's argv below still carries the typed
+    // values, so the printed command stays replayable on a machine without
+    // the config. The decision itself lives in rememberPatch, tested without
+    // a TTY — this block is only the I/O around it, offer-editor's split.
+    const patch = rememberPatch(
+      {
+        audience: extras.audience,
+        portrait: extras.portrait,
+        thumbnailBrief: extras.thumbnailBrief,
+      },
+      cfg,
+    );
+    if (patch !== null) {
+      const remember = unwrap(
+        await confirm({
+          message: "Remember these for future runs? (saves to ~/.ossclip/config.json)",
+          initialValue: true,
+        }),
+      ) as boolean;
+      if (remember) {
+        const path = saveConfigPatch(patch);
+        // Say where the answers went — offer-editor's rule: a preference
+        // saved silently is one the user cannot find again to take back.
+        console.log(`▸ saved ${Object.keys(patch).join(", ")} to ${path}`);
+      }
+    }
+  }
   if (chosen.includes("speaker")) {
     extras.speaker = unwrap(
       await text({
@@ -268,16 +467,16 @@ export async function produceWizard(
     // Follow-up under the same extra, like --clip's seconds prompt: a language
     // only means anything once a model is being picked, and a multilingual
     // fine-tune silently decodes English without it (Urdu field test
-    // 2026-08-05). A non-.en pick is multilingual by construction, so the
-    // prefill makes plain Enter the safe answer — `auto` lets whisper detect.
-    // Empty keeps whisper's en default, and produceArgv's default-elision
-    // rule then emits no flag at all.
+    // 2026-08-05). The prefill (whisperLanguagePrefill) makes plain Enter the
+    // safe answer: a curated fine-tune's own language, else `auto` for a
+    // non-.en pick. Empty keeps whisper's en default, and produceArgv's
+    // default-elision rule then emits no flag at all.
     const lang = (
       unwrap(
         await text({
           message: "Transcription language code (empty = default en)",
           placeholder: "ur",
-          initialValue: bareWhisperModelName(model).endsWith(".en") ? "" : "auto",
+          initialValue: whisperLanguagePrefill(model),
           defaultValue: "",
         }),
       ) as string
@@ -312,7 +511,9 @@ export async function produceWizard(
     cleanup,
     graphics,
     intent,
-    out: out || undefined,
+    // Already `string | undefined`: pickSavePath's use-default row IS the
+    // old empty answer — no --out, produce derives its own default.
+    out,
     extras,
   });
 }

package/src/interactive/thumbnail-approve.ts

@@ -0,0 +1,217 @@
+import { copyFile, writeFile } from "node:fs/promises";
+import {
+  ThumbnailConceptSchema,
+  approvedOverlayText,
+  buildThumbnailPrompt,
+  type GenerateThumbnailImageOptions,
+  type ThumbnailConcept,
+  type ThumbnailConceptApproved,
+} from "@ossclip/core";
+import { openInViewer } from "../open";
+import { select, text, unwrap } from "./prompts";
+
+/**
+ * The pre-render concept approval and the post-generation retry loop
+ * (thumbnail UX, 2026-08-16). Both exist for the same field incident class:
+ * the concept/image models make a judgement call the user only discovers
+ * AFTER a multi-minute render — approval moves the concept judgement before
+ * the render, the retry loop makes the image judgement cheap to redo.
+ *
+ * Every prompt goes through the injectable `ApprovePrompts` seam so the loop
+ * logic is testable with a scripted object — no TTY, no clack, the tty.ts
+ * doctrine applied one layer up. The default implementation wraps clack via
+ * ./prompts and inherits its cancel-exits-cleanly behavior (unwrap).
+ */
+
+export interface ApprovePrompts {
+  /** Returns the chosen option's value — already unwrapped, never a cancel symbol. */
+  select(opts: {
+    message: string;
+    options: { value: string; label: string; hint?: string }[];
+  }): Promise<string>;
+  /** Returns the typed text — already unwrapped. */
+  text(opts: { message: string; initialValue?: string; placeholder?: string }): Promise<string>;
+}
+
+/** The live clack-backed prompts; tests inject a scripted replacement. */
+export function clackApprovePrompts(): ApprovePrompts {
+  return {
+    select: async (opts) => unwrap(await select(opts)) as string,
+    text: async (opts) => unwrap(await text({ ...opts, defaultValue: "" })) as string,
+  };
+}
+
+/**
+ * The concept as the three lines the approval prompt displays. Pure so the
+ * formatting (overlay first — it is the one thing the viewer will read) is
+ * pinned without a TTY.
+ */
+export function formatConceptLines(concept: ThumbnailConcept): string[] {
+  return [
+    `  overlay: ${concept.overlayText}`,
+    `  scene:   ${concept.scene}`,
+    `  style:   ${concept.styleNotes}`,
+  ];
+}
+
+/**
+ * Re-validate a hand-edited concept: through the SAME schema the LLM's
+ * output takes (an edit is user input, parsed not coerced), plus
+ * `approvedOverlayText`'s WORD cap on the overlay — the schema caps
+ * characters, but overlay text at thumbnail size keeps a cover banner's 4-9
+ * word ceiling (§35), and an edit must not smuggle a paragraph past the cap
+ * the generated path enforces. The helper is thumbnailStep's exact
+ * treatment, shared so the image cache key never sees two spellings of one
+ * concept.
+ */
+export function editedConcept(fields: {
+  scene: string;
+  overlayText: string;
+  styleNotes: string;
+}): ThumbnailConcept {
+  const parsed = ThumbnailConceptSchema.parse(fields);
+  return { ...parsed, overlayText: approvedOverlayText(parsed.overlayText) };
+}
+
+export interface ApproveConceptArgs {
+  /**
+   * One concept call, note optional — produce injects the provider-backed
+   * call (with audience/brief steer and phase timing); tests inject a stub.
+   */
+  generateConcept: (note?: string) => Promise<ThumbnailConcept>;
+  /** A concept to present first (the workdir cache) — skips the initial call. */
+  initial?: ThumbnailConcept;
+  prompts?: ApprovePrompts;
+  log?: (line: string) => void;
+}
+
+/**
+ * The approval loop: display → use / edit / regenerate-with-note / skip.
+ * Returns what the caller writes into `thumbnail-concept-approved.json` —
+ * the approved concept, or `{skip: true}` so the post-render step (and every
+ * non-TTY replay) skips loudly instead of silently regenerating.
+ */
+export async function approveThumbnailConcept(
+  args: ApproveConceptArgs,
+): Promise<ThumbnailConceptApproved> {
+  const { prompts = clackApprovePrompts(), log = console.log } = args;
+  let concept = args.initial ?? (await args.generateConcept());
+  for (;;) {
+    log("▸ thumbnail concept:");
+    for (const line of formatConceptLines(concept)) log(line);
+    const choice = await prompts.select({
+      message: "Use this thumbnail concept?",
+      options: [
+        { value: "use", label: "use it" },
+        { value: "edit", label: "edit fields" },
+        { value: "regenerate", label: "regenerate with a note" },
+        { value: "skip", label: "skip thumbnail", hint: "the frame-grab cover stands" },
+      ],
+    });
+    if (choice === "use") return concept;
+    if (choice === "skip") return { skip: true };
+    if (choice === "edit") {
+      // Prefilled per field so an edit is a tweak, not a retype; the result
+      // loops back to the display so the user confirms what they typed.
+      concept = editedConcept({
+        overlayText: await prompts.text({
+          message: "Overlay text (3-6 punchy words)",
+          initialValue: concept.overlayText,
+        }),
+        scene: await prompts.text({ message: "Scene", initialValue: concept.scene }),
+        styleNotes: await prompts.text({ message: "Style notes", initialValue: concept.styleNotes }),
+      });
+      continue;
+    }
+    // regenerate: one note, one fresh concept call, back to the display.
+    const note = (
+      await prompts.text({
+        message: "What should the concept do differently?",
+        placeholder: "less abstract — show the actual terminal output",
+      })
+    ).trim();
+    concept = await args.generateConcept(note || undefined);
+  }
+}
+
+export interface ThumbnailRetryArgs {
+  /** The `<out>.thumbnail.png` the step wrote — overwritten on each retry. */
+  imagePath: string;
+  /** The workdir cache — overwritten too, or a warm re-run would revert the retry. */
+  imageCachePath: string;
+  /** The approved/generated concept — UNCHANGED across retries by design. */
+  concept: ThumbnailConcept;
+  apiKey: string;
+  model: string;
+  portrait: { data: string; mimeType: string };
+  /** The injected-generate seam (thumbnailStep's exactly) — tests never touch the SDK. */
+  generate: (opts: GenerateThumbnailImageOptions) => Promise<Uint8Array>;
+  /** The injected viewer seam (openInViewer's shape) — tests never spawn a viewer. */
+  open?: (path: string) => void;
+  prompts?: ApprovePrompts;
+  log?: (line: string) => void;
+}
+
+/**
+ * The post-generation retry loop: keep, or regenerate with a note. Each
+ * retry is ONE image call — the concept stays fixed and the note rides the
+ * image prompt as a must-honor revision (buildThumbnailPrompt's
+ * `revisionNote`) — and the loop asks again after every result, so the user
+ * can iterate until "keep". A failed retry keeps the previous image on disk
+ * (both files were only overwritten on success) and says so.
+ */
+export async function thumbnailRetryLoop(args: ThumbnailRetryArgs): Promise<void> {
+  const { prompts = clackApprovePrompts(), log = console.log, open = openInViewer } = args;
+  for (;;) {
+    // Show the image before EVERY keep/regenerate prompt — top of the loop,
+    // so each regeneration reopens the NEW file. The user is confirming what
+    // they see, not a path (thumbnail UX, 2026-08-17).
+    try {
+      open(args.imagePath);
+    } catch {
+      // A headless-ish env or a missing xdg-open must not kill an
+      // interactive confirm that can proceed on the printed path — same
+      // posture as openInBrowser's error handler.
+      log(`▸ could not open viewer — ${args.imagePath}`);
+    }
+    const choice = await prompts.select({
+      message: `Thumbnail written → ${args.imagePath}. Keep it?`,
+      options: [
+        { value: "keep", label: "keep" },
+        { value: "regenerate", label: "regenerate with a note" },
+      ],
+    });
+    if (choice === "keep") return;
+    const note = (
+      await prompts.text({
+        message: "What should change in the image?",
+        placeholder: "warmer lighting, less clutter behind me",
+      })
+    ).trim();
+    // An empty note would regenerate with zero new information — the same
+    // dice re-rolled at API cost. Re-ask instead of guessing what changed.
+    if (!note) continue;
+    try {
+      const bytes = await args.generate({
+        apiKey: args.apiKey,
+        model: args.model,
+        prompt: buildThumbnailPrompt(args.concept, true, note),
+        portrait: args.portrait,
+      });
+      // Cache first, then the destination — the same overwrite order a crash
+      // between the two degrades safest under: a stale destination beside a
+      // fresh cache self-heals on the next run's copy, the reverse would
+      // revert the user's retry on every warm re-run.
+      await writeFile(args.imageCachePath, bytes);
+      await copyFile(args.imageCachePath, args.imagePath);
+      log(`✓ thumbnail regenerated → ${args.imagePath}`);
+    } catch (err) {
+      // §132 posture verbatim from thumbnailStep: surface the API's message,
+      // never retry silently, and the previous image stands.
+      log(
+        `▸ thumbnail: regeneration failed (${err instanceof Error ? err.message : String(err)}) ` +
+          "— keeping the previous image",
+      );
+    }
+  }
+}

package/src/open.ts

@@ -1,24 +1,28 @@
 import { spawn } from "node:child_process";
 
 /**
- * Open a URL in the default browser, per platform. The old code spawned
- * macOS's `open` unconditionally — on Linux and Windows that ENOENT became
- * an unhandled 'error' event and took the whole edit server down with it.
+ * Open a target — URL or file path, every platform's opener treats them
+ * identically — in the OS default handler, per platform. The old code
+ * spawned macOS's `open` unconditionally — on Linux and Windows that ENOENT
+ * became an unhandled 'error' event and took the whole edit server down
+ * with it.
  *
  * Failure here is not an error: a headless box or WSL without a browser is
  * a normal place to run `ossclip edit` — print the URL and move on.
  */
 export function openCommand(
-  url: string,
+  target: string,
   platform: NodeJS.Platform,
 ): { bin: string; args: string[] } {
-  if (platform === "darwin") return { bin: "open", args: [url] };
+  if (platform === "darwin") return { bin: "open", args: [target] };
   if (platform === "win32") {
     // `start` is a cmd built-in, not an executable; the empty string is
-    // start's window-title slot so the URL isn't eaten as the title.
-    return { bin: "cmd", args: ["/c", "start", "", url] };
+    // start's window-title slot so the target isn't eaten as the title —
+    // load-bearing for file paths with spaces, which spawn quotes and
+    // `start` would otherwise read as its title argument.
+    return { bin: "cmd", args: ["/c", "start", "", target] };
   }
-  return { bin: "xdg-open", args: [url] };
+  return { bin: "xdg-open", args: [target] };
 }
 
 export function openInBrowser(url: string, platform: NodeJS.Platform = process.platform): void {
@@ -28,3 +32,17 @@ export function openInBrowser(url: string, platform: NodeJS.Platform = process.p
     console.log(`▸ couldn't open a browser here — open ${url} yourself`);
   });
 }
+
+/**
+ * Open a file in the OS default viewer — the thumbnail confirm needs the
+ * user to SEE the image before answering keep/regenerate, not squint at a
+ * path. Same posture as openInBrowser: a missing xdg-open on a headless-ish
+ * box logs one line and the interactive flow proceeds on the printed path.
+ */
+export function openInViewer(path: string, platform: NodeJS.Platform = process.platform): void {
+  const { bin, args } = openCommand(path, platform);
+  const child = spawn(bin, args, { stdio: "ignore", detached: false });
+  child.on("error", () => {
+    console.log(`▸ could not open viewer — ${path}`);
+  });
+}