ossclip 0.1.31 → 0.1.34

package/src/edit.ts

@@ -1,7 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
-import { copyFile, mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { homedir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -17,9 +17,27 @@ import {
   type YoutubePack,
   ThumbnailConceptApprovedSchema,
   ThumbnailConceptSchema,
+  appendUsageRun,
   approvedOverlayText,
   buildThumbnailPrompt,
+  captionCap,
+  captionForProvider,
+  checkDurationCaps,
+  createPostizProvider,
+  createProvider,
+  encodeEta,
+  formatUsageLine,
+  generateCaptionRegen,
+  generateYoutubePack,
+  YOUTUBE_PROMPT_VERSION,
+  deliveryEncodePlan,
+  ensureDeliveryFile,
+  PLATFORM_DURATION_CAPS_SEC,
+  PLATFORM_SIZE_CAP_BYTES,
+  probe,
+  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 +48,14 @@ import {
   PORTRAIT_MIME_TYPES,
   portraitMimeType,
   readCoverProvenance,
+  runWhisper,
   SegmentSchema,
+  spliceTranscript,
+  TranscriptSchema,
+  ungroundedTokens,
+  whisperPromptFor,
+  wordsInSpan,
+  type ModelPrice,
   type Segment,
   thumbnailImageCacheName,
   type CoverProvenance,
@@ -42,7 +67,9 @@ import {
 // drags in @ossclip/core's process runner and llm-detect, worth deferring off
 // server startup — open.ts is node:child_process + node:path and pure command
 // building, with nothing to defer.
+import { loadEnvFiles } from "./env";
 import { revealInFileManager } from "./open";
+import { REVIEWED_SCENES_BASENAME, renderReplayArgs } from "./render-replay-args";
 // The recorded-invocation reads live in cover.ts (2026-08-19): `ossclip
 // cover` needs the same out-resolution rule this server's thumbnail dest,
 // youtube markdown and reveal endpoint derive from, and two spellings of it
@@ -60,6 +87,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 +99,16 @@ import {
   type ResolvedPortrait,
 } from "./portrait-override";
 import { lastFlagValue, thumbnailPanelState } from "./thumbnail-panel";
+import { captionRegenProvider } from "./caption-regen-panel";
+import { binOnPath } from "./llm-detect";
+import {
+  attachDeliveryMedia,
+  buildPublishPosts,
+  publishConfigured,
+  publishReceiptPath,
+  readPublishReceipt,
+  sizeCapGroups,
+} from "./publish";
 
 /**
  * Where the built editor page lives (R18 §90b): `editor-dist/` inside this
@@ -94,6 +135,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 +271,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,11 +375,37 @@ 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;
+      /** produce's config fallback for `--audience` — the on-demand pack
+       * generation reads it the same way (typeof, never truthiness). */
+      audience?: unknown;
+      /** The caption-regenerate spend report prices through the same table
+       * produce does — absent in a stub, the defaults apply. */
+      pricing?: Record<string, ModelPrice>;
+    } & 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;
+    /** The publish endpoints' two ffmpeg-family shell-outs (the sliceAudio/
+     * runWhisper seam pattern) — tests stub a probe and a delivery encode
+     * instead of needing ffmpeg/ffprobe and a real render on the runner. */
+    probeVideo?: typeof probe;
+    ensureDelivery?: typeof ensureDeliveryFile;
     /** File-manager reveal seam (the `generateThumbnail` pattern) — tests
      * observe the revealed path instead of popping a real Finder/Explorer
      * window on the runner. */
     reveal?: (path: string) => void;
+    /** The caption-regenerate LLM seam (the `generateThumbnail` pattern for
+     * text): tests inject a fake provider factory and never touch a model. */
+    makeLlmProvider?: typeof createProvider;
     /**
      * The cover render seam, exactly like `generateThumbnail` above. Without
      * it `regenerateCover` lazily imports @ossclip/renderer and boots a
@@ -266,6 +413,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 +510,46 @@ 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;
+  /**
+   * One caption regeneration at a time (`/api/publish/regenerate`) — an LLM
+   * call costs money, and a double-click must not buy two. `thumbnailBusy`'s
+   * rule, its own flag: a caption rewrite must not block a thumbnail.
+   */
+  let captionRegenBusy = false;
+  /**
+   * One pack generation at a time (`/api/youtube/generate`) — an LLM call
+   * costs money, and a double-click must not buy two. `captionRegenBusy`'s
+   * rule, its own flag: generating the pack must not block a caption rewrite
+   * already in flight (they are different buttons in different panels).
+   */
+  let packGenBusy = false;
+  /**
+   * Where the in-flight publish is right now, for the panel's poll
+   * (2026-08-29): the POST runs the delivery encode synchronously — minutes
+   * of x264 behind one fetch — so `GET /api/publish/progress` reads this
+   * instead of the panel staring at a static button. Null whenever no publish
+   * is in flight; a POST's `finally` owns the reset so an error can't leave a
+   * stale "encoding" behind. Per server instance like the busy flags above.
+   */
+  let publishProgress: {
+    phase: "encoding" | "uploading";
+    pct: number | null;
+    etaSec: number | null;
+    speed: number | null;
+    /** The delivery file being encoded (from onStart) — a size-capped
+     * publish runs two sequential encodes, and a bare pct that resets to 0
+     * mid-publish looks like a hang unless the label names which file it
+     * restarted for. Null before the first onStart and while uploading. */
+    file: string | null;
+  } | null = null;
   /** 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
@@ -409,6 +604,33 @@ export async function startEditServer(
   // panel round-trips through youtube-pack-approved.json, which produce's Y2
   // block honors VERBATIM on every replay — an edit persisted there survives
   // into future renders with zero new plumbing.
+  /**
+   * The publish config, resolved FRESH per request — both halves of it.
+   *
+   * `loadConfig()` already re-read `config.json` every time, but the API key
+   * came from the process env, which is populated once at CLI startup: a user
+   * who set up Postiz while the editor was open got "not configured" until a
+   * restart, with `postizUrl` live and the key stale (2026-08-27). Re-running
+   * `loadEnvFiles` costs two small file reads on a button press and keeps the
+   * documented precedence exactly — it never clobbers a key the real
+   * environment already set, so a shell-provided key still wins.
+   *
+   * Skipped entirely when the caller injected `publishEnv` (tests own their
+   * environment, and reading the developer's real `~/.ossclip/.env` into a
+   * test would make the suite depend on the machine it runs on).
+   */
+  const resolvePublishConfig = (): ReturnType<typeof publishConfigured> => {
+    if (opts.publishEnv === undefined) loadEnvFiles();
+    return publishConfigured((opts.loadCfg ?? loadConfig)(), opts.publishEnv ?? process.env);
+  };
+  /** ffmpeg/ffprobe for the publish endpoints' probe + delivery encode —
+   * from the same config read the rest of the panel resolves through. The
+   * `?? "ffmpeg"` legs exist only for the narrowed `loadCfg` seam; the real
+   * `loadConfig()` always fills both. */
+  const publishTools = (): { ffmpegPath: string; ffprobePath: string } => {
+    const cfg = (opts.loadCfg ?? loadConfig)();
+    return { ffmpegPath: cfg.ffmpegPath ?? "ffmpeg", ffprobePath: cfg.ffprobePath ?? "ffprobe" };
+  };
   const approvedPackPath = (): string => join(workdir!, YOUTUBE_APPROVED_BASENAME);
   /** The pack the panel shows: the approved file first (the user's
    * decision), else the newest valid `youtube-<key>.json` cache (what the
@@ -555,6 +777,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
@@ -697,13 +1070,16 @@ export async function startEditServer(
           const chunks: Buffer[] = [];
           for await (const c of req) chunks.push(c as Buffer);
           let customOut: string | undefined;
+          let replan = false;
           try {
             const raw = Buffer.concat(chunks).toString();
             if (raw.trim()) {
-              const body = JSON.parse(raw) as { out?: string };
+              const body = JSON.parse(raw) as { out?: string; replan?: boolean };
               if (typeof body.out === "string" && body.out.trim()) {
                 customOut = body.out.trim();
               }
+              // Opt back into a fresh LLM plan (renderReplayArgs' why).
+              replan = body.replan === true;
             }
           } catch {
             // ignore
@@ -758,6 +1134,30 @@ export async function startEditServer(
             filteredArgs.push("--out", customOut);
             args = filteredArgs;
           }
+          // THE EDITOR IS THE AUTHORITY for a render started here: pin the
+          // plan the user just reviewed (`production.json`'s scenes) instead
+          // of letting `--produce` plan a fresh one that renumbers scenes and
+          // orphans their edits (renderReplayArgs owns the full why). Written
+          // to its own file rather than reusing `scenes-<key>.json`, which is
+          // keyed to a beat sheet this render may no longer match.
+          let scenesPath: string | undefined;
+          if (!replan) {
+            try {
+              const production = JSON.parse(
+                await readFile(join(workdir!, "production.json"), "utf8"),
+              ) as { scenes?: unknown };
+              if (Array.isArray(production.scenes) && production.scenes.length > 0) {
+                scenesPath = join(workdir!, REVIEWED_SCENES_BASENAME);
+                await writeFile(scenesPath, `${JSON.stringify(production.scenes, null, 2)}\n`);
+              }
+            } catch {
+              // No production.json, an old one without `scenes`, or an
+              // unwritable workdir: replay the recorded command rather than
+              // refuse to render (renderReplayArgs' no-plan case).
+              scenesPath = undefined;
+            }
+          }
+          args = renderReplayArgs(args, { scenesPath, replan });
           renderLines = [];
           renderExit = null;
           renderStartedAt = Date.now();
@@ -1185,6 +1585,619 @@ export async function startEditServer(
           return send(200, { ok: true, mdPath });
         }
 
+        if (url.pathname === "/api/youtube/generate" && req.method === "POST") {
+          // Generate the pack ON DEMAND (2026-08-29): a render produced
+          // without --youtube has no caption pack, and the publish modal
+          // dead-ended on "run produce with --youtube" — a full re-produce
+          // just to buy one LLM call. This writes the same CACHE file
+          // produce's Y2 block would have, never the approved file: approval
+          // stays the user's explicit act (PUT /api/youtube), and the user
+          // still reviews the captions before anything sends.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          // An LLM call costs money — one at a time, a second is a 409 like
+          // a second caption rewrite.
+          if (packGenBusy) {
+            return send(409, { error: "a caption-pack generation is already running" });
+          }
+          // Lenient transcript read but a 412 when it yields nothing — the
+          // /api/publish/regenerate posture, same reason: a pack with no
+          // transcript would be invented metadata. The words joined raw is
+          // the honest input the server has (regenerate made the same call);
+          // produce's stamped transcript needs the cut map, which only a
+          // produce run holds — the prompt tolerates plain text, the model
+          // just gets no measured chapters worth trusting.
+          let words: Array<{ text: string }> = [];
+          let lastWordEnd: number | null = null;
+          try {
+            const raw = JSON.parse(await readFile(join(workdir, "transcript.json"), "utf8")) as {
+              words?: unknown;
+            };
+            if (Array.isArray(raw.words)) {
+              words = raw.words.filter(
+                (w): w is { text: string } =>
+                  typeof (w as { text?: unknown } | null)?.text === "string",
+              );
+              for (const w of raw.words) {
+                const end = (w as { end?: unknown } | null)?.end;
+                if (typeof end === "number" && Number.isFinite(end)) {
+                  lastWordEnd = Math.max(lastWordEnd ?? 0, end);
+                }
+              }
+            }
+          } catch {
+            // absent/corrupt → the 412 below
+          }
+          if (words.length === 0) {
+            return send(412, {
+              error:
+                "no transcript in this workdir — the pack would have nothing to ground " +
+                "against; re-run `ossclip produce`.",
+            });
+          }
+          // The prompt's runtime ceiling: the output duration produce
+          // measured (render-props.json), else the transcript's last word
+          // end — source-clock, but the honest number available, and a
+          // raw-text transcript gets no measured chapters anyway.
+          let durationSec: number | null = null;
+          try {
+            const props = JSON.parse(await readFile(propsPath(), "utf8")) as {
+              outputDurationSec?: unknown;
+            };
+            if (
+              typeof props.outputDurationSec === "number" &&
+              Number.isFinite(props.outputDurationSec) &&
+              props.outputDurationSec > 0
+            ) {
+              durationSec = props.outputDurationSec;
+            }
+          } catch {
+            // corrupt props — the transcript fallback below
+          }
+          if (durationSec === null && lastWordEnd !== null && lastWordEnd > 0) {
+            durationSec = lastWordEnd;
+          }
+          if (durationSec === null) {
+            return send(412, {
+              error: "cannot determine the video's duration — re-run `ossclip produce`.",
+            });
+          }
+          const cmd = await readCommandRecord();
+          const cfg = (opts.loadCfg ?? loadConfig)();
+          // The editorial steer produce would have used: the recorded flags
+          // first, then produce's own defaults when a flag is absent —
+          // intent has none, audience falls back to the config's `audience`
+          // (produce.ts's typed read: typeof, never truthiness).
+          const intent = lastFlagValue(cmd?.args ?? [], ["--intent"]);
+          const audience =
+            lastFlagValue(cmd?.args ?? [], ["--audience"]) ??
+            (typeof cfg.audience === "string" ? cfg.audience : undefined);
+          // hook/coverText come from the beat sheet in produce; a produce
+          // run that planned left its sheet cached in the workdir. The
+          // shipped cover headline (cover.json, possibly the user's own
+          // words) backstops coverText. All optional — buildYoutubePrompt
+          // omits absent lines, exactly as a no-beat-sheet produce does.
+          let hook: string | undefined;
+          let coverText: string | undefined;
+          const beatCache = await newestWorkdirFile(
+            (n) => n.startsWith("beatsheet-") && n.endsWith(".json"),
+          );
+          if (beatCache !== null) {
+            try {
+              const sheet = JSON.parse(await readFile(beatCache, "utf8")) as {
+                hook?: unknown;
+                coverText?: unknown;
+              };
+              if (typeof sheet.hook === "string" && sheet.hook.trim().length > 0) {
+                hook = sheet.hook;
+              }
+              if (typeof sheet.coverText === "string" && sheet.coverText.trim().length > 0) {
+                coverText = sheet.coverText;
+              }
+            } catch {
+              // a corrupt cache loses a steer line, never the generation
+            }
+          }
+          if (coverText === undefined) {
+            const provenance = await readCoverProvenance(workdir);
+            if (provenance !== null && provenance.text.trim().length > 0) {
+              coverText = provenance.text;
+            }
+          }
+          // Env fresh per press, then the caption regenerate's provider
+          // resolution verbatim — the same "which LLM does this project
+          // use" question with the same three-rung answer.
+          if (opts.publishEnv === undefined) loadEnvFiles();
+          const env = opts.publishEnv ?? process.env;
+          const usagePath = join(workdir, "usage.json");
+          let usageLog: unknown = null;
+          try {
+            usageLog = JSON.parse(await readFile(usagePath, "utf8"));
+          } catch {
+            // no log yet — the resolution falls through to the pin/detection
+          }
+          const resolved = captionRegenProvider({
+            usageLog,
+            commandArgs: cmd?.args ?? null,
+            env,
+            hasBin: (bin) => binOnPath(bin, env),
+          });
+          if (resolved.status === "unavailable") {
+            return send(412, { error: resolved.reason });
+          }
+          const provider = (opts.makeLlmProvider ?? createProvider)(resolved.provider);
+          packGenBusy = true;
+          try {
+            let pack: YoutubePack;
+            try {
+              pack = await generateYoutubePack(provider, {
+                transcriptText: words.map((w) => w.text).join(" "),
+                ...(intent !== undefined ? { intent } : {}),
+                ...(hook !== undefined ? { hook } : {}),
+                ...(coverText !== undefined ? { coverText } : {}),
+                ...(audience !== undefined ? { audience } : {}),
+                durationSec,
+              });
+            } catch (err) {
+              // 200 with ok:false, the caption regenerate's posture: a
+              // provider failure is a sentence the panel shows VERBATIM,
+              // never a dead 500. Nothing is cached (§106).
+              return send(200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+            }
+            const pricing = cfg.pricing ?? {};
+            // The spend is real, so it survives the session — the caption
+            // regenerate's append, atomically.
+            const nextLog = appendUsageRun(
+              usageLog,
+              { at: new Date().toISOString(), records: provider.usage },
+              pricing,
+            );
+            const usageTmp = `${usagePath}.tmp`;
+            await writeFile(usageTmp, JSON.stringify(nextLog, null, 2));
+            await rename(usageTmp, usagePath);
+            // A `youtube-<key>.json` cache, keyed on the provider asked like
+            // produce's Y2 write — deliberately NOT produce's exact key: that
+            // key hashes the cut map's spans and the stamped transcript,
+            // which only a produce run holds, and matching it would falsely
+            // claim cache identity with an answer built from different
+            // inputs. mtime is what makes this pack current: both
+            // currentYoutubePack and loadPublishPack sort caches newest
+            // first. Atomic like the approved-pack write.
+            const key = createHash("sha1")
+              .update(
+                JSON.stringify([
+                  YOUTUBE_PROMPT_VERSION,
+                  resolved.provider,
+                  intent ?? "",
+                  audience ?? "",
+                  words.map((w) => w.text),
+                ]),
+              )
+              .digest("hex")
+              .slice(0, 8);
+            const packPath = join(workdir, `youtube-${key}.json`);
+            const packTmp = `${packPath}.tmp`;
+            await writeFile(packTmp, JSON.stringify(pack, null, 2));
+            await rename(packTmp, packPath);
+            return send(200, { ok: true, usage: formatUsageLine(provider.usage, pricing) });
+          } finally {
+            packGenBusy = false;
+          }
+        }
+
+        // ---- 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 = resolvePublishConfig();
+          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();
+          // Pre-flight duration for the panel, read leniently (the
+          // /api/cleanup posture): a missing ffprobe or an unreadable render
+          // degrades to null — the panel loses the gray-out, never the modal —
+          // and POST re-checks the caps authoritatively anyway.
+          let durationSec: number | null = null;
+          if (out !== null && existsSync(out)) {
+            try {
+              durationSec = (await (opts.probeVideo ?? probe)(publishTools(), out)).duration;
+            } catch {
+              // degrade — the caps still apply server-side on POST
+            }
+          }
+          let integrations: Array<{
+            id: string;
+            provider: string;
+            name: string;
+            caption: string;
+            durationCapSec: number | null;
+            sizeCapBytes: number | null;
+          }> = [];
+          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) : "",
+              // Null = no cap (limits.ts: absence means unlimited) — the
+              // panel grays out a channel only against a cap that exists.
+              durationCapSec: PLATFORM_DURATION_CAPS_SEC[t.provider] ?? null,
+              // The platform's upload byte ceiling, same posture: null means
+              // uncapped, a number means this channel gets its own smaller
+              // delivery encode (limits.ts: Instagram's ~100MB URL-fetch cap).
+              sizeCapBytes: PLATFORM_SIZE_CAP_BYTES[t.provider] ?? null,
+            }));
+          } 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),
+            durationSec,
+            receipt: await readPublishReceipt(workdir),
+          });
+        }
+
+        if (url.pathname === "/api/publish" && req.method === "POST") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const configured = resolvePublishConfig();
+          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(),
+              // What uploads (the CLI's --delivery): auto (default) builds
+              // the cached delivery encode, master sends the untouched render.
+              delivery: z.enum(["auto", "master"]).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();
+            let 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;
+            });
+            // Same core helpers, same semantics as the CLI (checkDurationCaps
+            // + ensureDeliveryFile — one spelling of the rules): drop the
+            // channels this video can never land on, publish the rest, and
+            // only when EVERY pick is over its cap refuse the whole request.
+            const tools = publishTools();
+            const masterProbe = await (opts.probeVideo ?? probe)(tools, out);
+            const violations = checkDurationCaps(picked, masterProbe.duration);
+            // Duration entries keep their original shape; size entries carry
+            // a `reason` and the cap that doomed them — additive fields only,
+            // so an older panel reading `dropped` keeps working.
+            const dropped: Array<Record<string, unknown>> = violations.map((v) => ({
+              id: v.target.id,
+              provider: v.target.provider,
+              name: v.target.name,
+              capSec: v.capSec,
+            }));
+            if (violations.length > 0) {
+              const over = new Set(violations.map((v) => v.target.id));
+              picked = picked.filter((t) => !over.has(t.id));
+              if (picked.length === 0) {
+                return send(412, {
+                  error:
+                    `every picked channel refuses a ${Math.round(masterProbe.duration)}s video — ` +
+                    "nothing to publish",
+                  dropped,
+                });
+              }
+            }
+            // Size-cap pre-check with the pure plan (the CLI's semantics,
+            // one spelling): an unattainable cap drops the channel BEFORE
+            // any encode — ensureDeliveryFile THROWS on unattainable, and a
+            // 502 with ffmpeg arithmetic in it is not a drop-and-continue.
+            const masterSizeBytes = (await stat(out)).size;
+            const src = {
+              width: masterProbe.width,
+              height: masterProbe.height,
+              fps: masterProbe.fps,
+              duration: masterProbe.duration,
+              sizeBytes: masterSizeBytes,
+            };
+            let capGroups = sizeCapGroups(picked);
+            if (parsed.data.delivery !== "master") {
+              for (const [capBytes, group] of capGroups) {
+                const capped = deliveryEncodePlan(src, { sizeCapBytes: capBytes });
+                if (capped !== null && "unattainable" in capped) {
+                  for (const t of group) {
+                    dropped.push({
+                      id: t.id,
+                      provider: t.provider,
+                      name: t.name,
+                      sizeCapBytes: capBytes,
+                      reason: "size",
+                    });
+                  }
+                  const over = new Set(group.map((t) => t.id));
+                  picked = picked.filter((t) => !over.has(t.id));
+                }
+              }
+              if (picked.length === 0) {
+                return send(412, {
+                  error:
+                    `every picked channel's size cap is unattainable for a ` +
+                    `${Math.round(masterProbe.duration)}s video — nothing to publish`,
+                  dropped,
+                });
+              }
+              capGroups = sizeCapGroups(picked);
+            }
+            const posts = buildPublishPosts(pack, picked).map((p) => ({
+              ...p,
+              caption: parsed.data.captions?.[p.target.id] ?? p.caption,
+            }));
+            // Synchronous encodes (~1–3 min each, fetch won't time out) — a
+            // job/poll model for the WORK is a noted follow-up, but the
+            // PROGRESS is polled: /api/publish/progress reads the state the
+            // onProgress callback below keeps current. Sequential per cap
+            // group (two ffmpegs racing for cores would slow both), so pct
+            // simply runs 0→100 once per file and `file` names which one.
+            let uploadPath = out;
+            const cappedPaths = new Map<number, string>();
+            if (parsed.data.delivery !== "master") {
+              // `workdir` is a mutable binding, so its non-null narrowing
+              // from the top of the handler doesn't survive into a closure —
+              // capture it while narrowed.
+              const wd = workdir;
+              const runEnsure = async (
+                sizeCapBytes?: number,
+              ): ReturnType<typeof ensureDeliveryFile> => {
+                let currentFile: string | null = null;
+                publishProgress = { phase: "encoding", pct: 0, etaSec: null, speed: null, file: null };
+                return (opts.ensureDelivery ?? ensureDeliveryFile)(tools, wd, out, {
+                  ...(sizeCapBytes !== undefined ? { sizeCapBytes } : {}),
+                  onStart: (name) => {
+                    currentFile = name;
+                    publishProgress = { phase: "encoding", pct: 0, etaSec: null, speed: null, file: name };
+                  },
+                  onProgress: (p) => {
+                    publishProgress = {
+                      phase: "encoding",
+                      // Percent against the MASTER's duration — the delivery
+                      // encode preserves it, so out_time maps 1:1.
+                      pct:
+                        p.outTimeSec !== undefined && masterProbe.duration > 0
+                          ? Math.min(
+                              100,
+                              Math.round((p.outTimeSec / masterProbe.duration) * 100),
+                            )
+                          : null,
+                      etaSec:
+                        p.outTimeSec !== undefined && p.speed !== undefined
+                          ? encodeEta(masterProbe.duration, p.outTimeSec, p.speed)
+                          : null,
+                      speed: p.speed ?? null,
+                      file: currentFile,
+                    };
+                  },
+                });
+              };
+              uploadPath = (await runEnsure()).path;
+              // One encode per DISTINCT cap — the bitrate-bearing filename is
+              // the cache key, so a capped plan that lands on the default
+              // file's name cache-hits instead of re-encoding.
+              for (const capBytes of capGroups.keys()) {
+                cappedPaths.set(capBytes, (await runEnsure(capBytes)).path);
+              }
+            }
+            // No upload ETA — Postiz's multipart upload gives us nothing to
+            // measure, so the phase alone is the signal.
+            publishProgress = { phase: "uploading", pct: null, etaSec: null, speed: null, file: null };
+            const result = await provider.publish({
+              videoPath: uploadPath,
+              posts: attachDeliveryMedia(posts, uploadPath, cappedPaths),
+              when,
+            });
+            await writeFile(publishReceiptPath(workdir), `${JSON.stringify(result, null, 2)}\n`);
+            return send(200, { ok: true, receipt: result, dropped });
+          } 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) });
+          } finally {
+            publishProgress = null;
+          }
+        }
+
+        if (url.pathname === "/api/publish/progress" && req.method === "GET") {
+          // Where the in-flight publish is — 200 always, `progress: null`
+          // when idle (a cache hit or a skip-plan publish never enters the
+          // encoding phase, and the panel keeps its static line for that).
+          return send(200, { progress: publishProgress });
+        }
+
+        if (url.pathname === "/api/publish/regenerate" && req.method === "POST") {
+          // Rewrite ONE network's caption with the LLM the produce run used
+          // (handoff 2026-08-29 item 4): the prompt carries the transcript,
+          // the caption AS THE PANEL HOLDS IT and the user's correction, and
+          // the replacement text rides back into the panel's box. Nothing
+          // auto-sends and nothing writes to the pack — the user still
+          // reviews, edits and presses Publish.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          // An LLM call costs money — one at a time, a second is a 409 like
+          // a second thumbnail.
+          if (captionRegenBusy) {
+            return send(409, { error: "a caption regeneration is already running" });
+          }
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          // `currentCaption` is deliberately the client's text — the ONE
+          // body-steered value beyond the ask itself, because the box may
+          // hold the user's manual edits and the model must see what the
+          // user sees. It steers only prompt text, never a path or a spawn.
+          const parsed = z
+            .object({
+              network: z.string().min(1),
+              instruction: z.string().min(1),
+              currentCaption: z.string(),
+            })
+            .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+          if (!parsed.success) return send(400, { error: parsed.error.message });
+          // Lenient transcript read (the GET /api/transcript posture), but a
+          // 412 when it yields nothing: a rewrite with no transcript would be
+          // a rewrite with no factual evidence, which is the exact failure
+          // this endpoint exists to repair.
+          let transcript: { language: string; words: Array<{ text: string }> } | null = null;
+          try {
+            const raw = JSON.parse(await readFile(join(workdir, "transcript.json"), "utf8")) as {
+              language?: unknown;
+              words?: unknown;
+            };
+            if (Array.isArray(raw.words)) {
+              transcript = {
+                language: typeof raw.language === "string" ? raw.language : "en",
+                words: raw.words.filter(
+                  (w): w is { text: string } =>
+                    typeof (w as { text?: unknown } | null)?.text === "string",
+                ),
+              };
+            }
+          } catch {
+            // absent/corrupt → the 412 below
+          }
+          if (transcript === null || transcript.words.length === 0) {
+            return send(412, {
+              error:
+                "no transcript in this workdir — the rewrite would have nothing to " +
+                "ground against; re-run `ossclip produce`.",
+            });
+          }
+          // Env fresh per press, resolvePublishConfig's rule: a key set after
+          // startup must count. Skipped when tests own the environment.
+          if (opts.publishEnv === undefined) loadEnvFiles();
+          const env = opts.publishEnv ?? process.env;
+          const usagePath = join(workdir, "usage.json");
+          let usageLog: unknown = null;
+          try {
+            usageLog = JSON.parse(await readFile(usagePath, "utf8"));
+          } catch {
+            // no log yet — the resolution falls through to the pin/detection
+          }
+          const cmd = await readCommandRecord();
+          const resolved = captionRegenProvider({
+            usageLog,
+            commandArgs: cmd?.args ?? null,
+            env,
+            hasBin: (bin) => binOnPath(bin, env),
+          });
+          if (resolved.status === "unavailable") {
+            // Precondition, not a generation failure — 412 like a thumbnail
+            // regenerate on an unavailable project.
+            return send(412, { error: resolved.reason });
+          }
+          const provider = (opts.makeLlmProvider ?? createProvider)(resolved.provider);
+          captionRegenBusy = true;
+          try {
+            let caption: string;
+            try {
+              caption = await generateCaptionRegen(provider, {
+                network: parsed.data.network,
+                currentCaption: parsed.data.currentCaption,
+                instruction: parsed.data.instruction,
+                transcriptText: transcript.words.map((w) => w.text).join(" "),
+                charCap: captionCap(parsed.data.network),
+              });
+            } catch (err) {
+              // 200 with ok:false, the thumbnail regenerate's posture: a
+              // provider failure is a sentence the panel shows VERBATIM,
+              // never a dead 500.
+              return send(200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+            }
+            const pricing = (opts.loadCfg ?? loadConfig)().pricing ?? {};
+            // The spend is real, so it survives the session: appended into
+            // the workdir's usage log the way produce appends its runs.
+            // Atomic like the overrides write — /api/usage may read it at
+            // any moment.
+            const nextLog = appendUsageRun(
+              usageLog,
+              { at: new Date().toISOString(), records: provider.usage },
+              pricing,
+            );
+            const tmp = `${usagePath}.tmp`;
+            await writeFile(tmp, JSON.stringify(nextLog, null, 2));
+            await rename(tmp, usagePath);
+            // Advisory ONLY, never a block: captions legitimately carry
+            // brand and platform words the take never speaks. The `--speaker`
+            // pin counts as spoken vocabulary for checkGrounding's §39
+            // reason — the channel name is in nearly every caption.
+            const speaker = lastFlagValue(cmd?.args ?? [], ["--speaker"]);
+            const notes = [...new Set(ungroundedTokens(caption, transcript, speaker))].map(
+              (token) => `⚠ grounding: "${token}" — not in the take`,
+            );
+            return send(200, {
+              ok: true,
+              caption,
+              usage: formatUsageLine(provider.usage, pricing),
+              notes,
+            });
+          } finally {
+            captionRegenBusy = false;
+          }
+        }
+
         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