@ossclip/core 0.1.31 → 0.1.34

package/src/publish/postiz.ts

@@ -0,0 +1,320 @@
+import { basename } from "node:path";
+import { z } from "zod/v4";
+import type {
+  PublishPost,
+  PublishProvider,
+  PublishReceipt,
+  PublishRequest,
+  PublishTarget,
+  PublishWhen,
+} from "./provider";
+
+/**
+ * The Postiz implementation of `PublishProvider` — a self-hosted Postiz
+ * instance (https://github.com/gitroomhq/postiz-app) the USER runs and has
+ * connected their social accounts to; ossclip only speaks its public HTTP
+ * API (https://docs.postiz.com/public-api) and vendors nothing (Postiz is
+ * AGPL; calling an API is not derivation).
+ *
+ * Contract, per those docs: base `{url}/api/public/v1`, `Authorization:
+ * <apiKey>` verbatim (NOT `Bearer <apiKey>`), `POST /upload` (multipart →
+ * `{id, path}`), `GET /integrations`, `POST /posts` with
+ * `{type, date, posts: [{integration:{id}, value:[{content, image:[...]}],
+ * settings:{__type: <provider>}}]}`. Rate limit 90 posts/hr self-hosted.
+ *
+ * Error posture is the OPPOSITE of telemetry.ts: a publish is the user's
+ * explicit action on their own content, so every non-2xx throws with the
+ * method, path, status and a body snippet — no retries, no swallowing, no
+ * partial state pretending to be success.
+ */
+
+/** `GET /integrations` — only the fields ossclip reads; unknown keys drop. */
+export const PostizIntegrationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  /** The platform identifier ("linkedin", "x", "instagram", ...). */
+  identifier: z.string(),
+  disabled: z.boolean().optional(),
+});
+export const PostizIntegrationsSchema = z.array(PostizIntegrationSchema);
+
+/** `POST /upload` — the media reference `/posts` embeds. */
+export const PostizUploadSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+});
+export type PostizUpload = z.infer<typeof PostizUploadSchema>;
+
+/**
+ * Connected accounts → publish targets. Disabled integrations are dropped
+ * here, not at selection time — an account Postiz itself won't post to must
+ * never appear in a picker.
+ */
+export function parseIntegrations(json: unknown): PublishTarget[] {
+  const parsed = PostizIntegrationsSchema.parse(json);
+  return parsed
+    .filter((i) => i.disabled !== true)
+    .map((i) => ({ id: i.id, provider: i.identifier, name: i.name }));
+}
+
+/**
+ * `/posts` accepts one request for MANY integrations — one unit against the
+ * 90/hr limit, and atomic from ossclip's side. Pure: the caller passes the
+ * already-uploaded media ref and the date, so the exact payload is testable
+ * (and `--dry-run` printable) without a network or a clock.
+ *
+ * `settings.__type` must name the integration's platform; beyond that the
+ * per-provider settings surface is Postiz's own validation domain — ossclip
+ * sends the minimum and surfaces Postiz's errors verbatim rather than
+ * duplicating (and drifting from) that matrix. YouTube is the one platform
+ * whose settings carry a required title, so a post's `title` passes through.
+ *
+ * Media comes in two shapes because posts can carry per-post files now
+ * (2026-08-29: Instagram's size cap gets its own smaller encode, everyone
+ * else shares the default — `PublishPost.videoPath`): a single upload keeps
+ * the original one-file contract for callers with no per-post media (the
+ * CLI's dry-run placeholder included), while the map form pairs every
+ * distinct `videoPath` with its upload and REQUIRES the default path the
+ * lookup falls back to — the union makes forgetting it a type error, not a
+ * runtime surprise.
+ */
+export type PostsPayloadMedia =
+  | { media: PostizUpload; defaultVideoPath?: undefined }
+  | { media: ReadonlyMap<string, PostizUpload>; defaultVideoPath: string };
+
+export function buildPostsPayload(
+  args: {
+    posts: PublishPost[];
+    when: PublishWhen;
+    dateIso: string;
+  } & PostsPayloadMedia,
+): Record<string, unknown> {
+  // instanceof on the property does not narrow the sibling `defaultVideoPath`
+  // through the union, so split the two shapes once up front.
+  const byPath = args.media instanceof Map ? (args.media as ReadonlyMap<string, PostizUpload>) : null;
+  const single = byPath === null ? (args.media as PostizUpload) : null;
+  const uploadFor = (p: PublishPost): PostizUpload => {
+    if (single !== null) {
+      // Single-upload shape: there is no path→upload pairing to consult, so a
+      // post asking for its own file would silently get the WRONG video —
+      // worse than any throw (2207077 at least fails; a LinkedIn post carrying
+      // the Instagram encode publishes).
+      if (p.videoPath !== undefined) {
+        throw new Error(
+          `post for ${p.target.provider} carries its own videoPath but buildPostsPayload got a single upload — pass the media map`,
+        );
+      }
+      return single;
+    }
+    const path = p.videoPath ?? args.defaultVideoPath;
+    const upload = path === undefined ? undefined : byPath!.get(path);
+    // publish() derives its upload set from the same `p.videoPath ??
+    // default` expression, so a miss is a caller bug — but see above: wrong
+    // video beats no video for worst outcome.
+    if (upload === undefined) throw new Error(`no upload for media path ${path}`);
+    return upload;
+  };
+  return {
+    type: args.when.kind === "now" ? "now" : "schedule",
+    date: args.when.kind === "at" ? args.when.iso : args.dateIso,
+    shortLink: false,
+    // Required by /posts' DTO as a top-level array ("tags should not be null
+    // or undefined" — the 2026-08-27 live E2E's first real request bounced on
+    // it). Always empty: calendar tags are a Postiz-UI concept ossclip has no
+    // gesture for.
+    tags: [],
+    posts: args.posts.map((p) => {
+      const upload = uploadFor(p);
+      return {
+        integration: { id: p.target.id },
+        value: [{ content: p.caption, image: [{ id: upload.id, path: upload.path }] }],
+        settings: {
+          __type: p.target.provider,
+          ...(p.title !== undefined ? { title: p.title } : {}),
+          // YouTube's privacy status is REQUIRED by Postiz's DTO (`type`,
+          // @IsDefined) — without it the whole /posts call is rejected at
+          // validation and nothing publishes, not just the YouTube post
+          // (2026-08-28). `private` is the default on purpose: the other
+          // platforms post publicly, but an accidental `--all` must not push to
+          // a subscriber list, and making a private video public in YouTube
+          // Studio is one click where un-publishing is not.
+          ...(p.target.provider === "youtube"
+            ? { type: p.youtubePrivacy ?? "private" }
+            : {}),
+          // Instagram's own required setting (`post_type`, @IsDefined — the
+          // second one a real publish found, at the same cost: a 400 AFTER the
+          // whole video had uploaded). Always `post`: ossclip renders a
+          // finished short, and a story expires in 24 hours, which nobody
+          // publishing a produced video is asking for.
+          ...(p.target.provider === "instagram" ? { post_type: "post" } : {}),
+        },
+      };
+    }),
+  };
+}
+
+/**
+ * Post ids out of whatever shape `/posts` answers with. Lenient BY DESIGN,
+ * unlike every other parse here: the 2xx status is the success signal, the
+ * ids are a convenience for the receipt, and a Postiz version that renames
+ * this envelope must not turn an accepted publish into a thrown "failure"
+ * after the posts already went out.
+ */
+export function extractPostIds(json: unknown): string[] {
+  const items = Array.isArray(json)
+    ? json
+    : typeof json === "object" && json !== null && Array.isArray((json as { posts?: unknown }).posts)
+      ? ((json as { posts: unknown[] }).posts)
+      : [json];
+  const ids: string[] = [];
+  for (const item of items) {
+    if (typeof item === "object" && item !== null) {
+      const id = (item as { id?: unknown; postId?: unknown }).id ?? (item as { postId?: unknown }).postId;
+      if (typeof id === "string") ids.push(id);
+    }
+  }
+  return ids;
+}
+
+/** `postizUrl` as the API base: trailing slashes dropped, `/api/public/v1`
+ * appended unless the user already wrote it. */
+export function postizApiBase(url: string): string {
+  const trimmed = url.replace(/\/+$/, "");
+  return trimmed.endsWith("/api/public/v1") ? trimmed : `${trimmed}/api/public/v1`;
+}
+
+export class PostizHttpError extends Error {
+  constructor(
+    readonly method: string,
+    readonly path: string,
+    readonly status: number,
+    bodySnippet: string,
+  ) {
+    const hint =
+      status === 401 || status === 403
+        ? " — Postiz rejected the API key (Settings → Public API in your Postiz instance)"
+        : status === 413
+          ? // Usually NOT Postiz: a reverse proxy in front of it refuses the
+            // body first (Cloudflare's free plan caps a proxied upload at
+            // 100MB — a 171MB render bounced on it during the 2026-08-27 live
+            // E2E, with Cloudflare's own HTML as the "Postiz" answer). Name the
+            // proxy and the way through, since tuning Postiz would do nothing.
+            " — the upload was refused as too large. A reverse proxy in front of Postiz is the" +
+            " usual cause (Cloudflare's free plan caps proxied uploads at 100MB); point" +
+            " postizUrl at the instance directly (its LAN/VPN address) or raise the proxy's limit"
+          : status === 429
+            ? " — Postiz rate limit (90 posts/hour per self-hosted instance)"
+            : "";
+    super(`Postiz ${method} ${path} failed: ${status}${hint}${bodySnippet ? `\n${bodySnippet}` : ""}`);
+    this.name = "PostizHttpError";
+  }
+}
+
+export interface PostizProviderOptions {
+  baseUrl: string;
+  apiKey: string;
+  fetchImpl?: typeof fetch;
+  /** Per-request cap. Uploads carry whole videos — default is generous. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const BODY_SNIPPET_CHARS = 300;
+
+export function createPostizProvider(opts: PostizProviderOptions): PublishProvider {
+  const base = postizApiBase(opts.baseUrl);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  const request = async (method: string, path: string, body?: BodyInit, headers?: Record<string, string>): Promise<unknown> => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    let res: Response;
+    try {
+      res = await fetchImpl(`${base}${path}`, {
+        method,
+        headers: { Authorization: opts.apiKey, ...headers },
+        body,
+        signal: ac.signal,
+      });
+    } catch (err) {
+      throw new Error(
+        `Postiz ${method} ${path} unreachable at ${base}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+      throw new PostizHttpError(method, path, res.status, text.slice(0, BODY_SNIPPET_CHARS));
+    }
+    try {
+      return text.length > 0 ? JSON.parse(text) : null;
+    } catch {
+      throw new Error(`Postiz ${method} ${path} answered non-JSON: ${text.slice(0, BODY_SNIPPET_CHARS)}`);
+    }
+  };
+
+  return {
+    name: "postiz",
+    async listTargets(): Promise<PublishTarget[]> {
+      return parseIntegrations(await request("GET", "/integrations"));
+    },
+    async publish(req: PublishRequest): Promise<PublishReceipt> {
+      const { openAsBlob } = await import("node:fs");
+      // Each DISTINCT file uploads exactly once: a size-capped platform
+      // carries its own smaller encode (`PublishPost.videoPath`, 2026-08-29)
+      // while the rest share the request default, and posts then map to
+      // their own media in the payload. Sequential on purpose — uploads are
+      // hundreds of MB, and parallelism buys contention, not time.
+      const paths = [...new Set(req.posts.map((p) => p.videoPath ?? req.videoPath))];
+      const uploads = new Map<string, PostizUpload>();
+      for (const path of paths) {
+        // openAsBlob streams the file into multipart form-data without ever
+        // holding the whole video in memory — a rendered short is routinely
+        // hundreds of MB, and a string/Buffer round-trip would double it.
+        const blob = await openAsBlob(path, { type: "video/mp4" });
+        const form = new FormData();
+        form.append("file", blob, basename(path));
+        try {
+          uploads.set(path, PostizUploadSchema.parse(await request("POST", "/upload", form)));
+        } catch (err) {
+          // "POST /upload failed" alone no longer says WHICH file when
+          // several are in flight — name it.
+          throw new Error(
+            `${err instanceof Error ? err.message : String(err)}\n(while uploading ${path})`,
+          );
+        }
+      }
+
+      const payload = buildPostsPayload({
+        posts: req.posts,
+        when: req.when,
+        dateIso: new Date().toISOString(),
+        media: uploads,
+        defaultVideoPath: req.videoPath,
+      });
+      let answer: unknown;
+      try {
+        answer = await request("POST", "/posts", JSON.stringify(payload), {
+          "content-type": "application/json",
+        });
+      } catch (err) {
+        // The media is already up — say so, so a retry is one request, not
+        // a re-upload of the whole video.
+        const ids = [...uploads.values()].map((u) => u.id).join(", ");
+        throw new Error(
+          `${err instanceof Error ? err.message : String(err)}\n` +
+            `(the video uploaded fine — media id ${ids}; retrying will re-upload it)`,
+        );
+      }
+      return {
+        backend: "postiz",
+        postIds: extractPostIds(answer),
+        publishedAt: new Date().toISOString(),
+        when: req.when,
+        targets: req.posts.map((p) => p.target),
+      };
+    },
+  };
+}

package/src/publish/progress.ts

@@ -0,0 +1,75 @@
+/**
+ * Encode progress for the delivery encode (2026-08-29): a real 5-minute video
+ * spends minutes in x264 with zero feedback — the CLI line and the editor
+ * panel both need percent + ETA, so the parsing lives here, pure, where both
+ * can reach it.
+ *
+ * ffmpeg's `-progress pipe:1` emits key=value lines on stdout roughly twice a
+ * second; this module turns those into { outTimeSec, speed } and the ETA
+ * arithmetic. No spawning here — encodeDelivery owns the ffmpeg call.
+ */
+
+export interface FfmpegProgress {
+  /** How far into the OUTPUT the encode is, in seconds. */
+  outTimeSec?: number;
+  /** Encode speed as a multiple of realtime (`speed=1.53x` → 1.53). */
+  speed?: number;
+}
+
+/**
+ * Parse a chunk of ffmpeg's `-progress` key=value stream. Returns the LAST
+ * value seen per key in this chunk — the stream repeats the block every
+ * ~500ms, and only the newest matters. `N/A` values (the first block, before
+ * ffmpeg has numbers) are ignored, and unparseable text yields nothing rather
+ * than a guess. The caller keeps a running latest across chunks; feeding only
+ * complete lines is also the caller's job (a chunk boundary can split a line
+ * mid-value, and half a number parses as the wrong number).
+ */
+export function parseFfmpegProgress(chunk: string): FfmpegProgress {
+  const out: FfmpegProgress = {};
+  for (const line of chunk.split(/\r?\n/)) {
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    if (value.length === 0 || value === "N/A") continue;
+    // out_time_us preferred; out_time_ms is ALSO microseconds despite the
+    // name (long-standing ffmpeg quirk — trusting the name would report a
+    // 1000x-too-long encode), out_time is the HH:MM:SS.xx spelling.
+    if (key === "out_time_us" || key === "out_time_ms") {
+      const us = Number(value);
+      if (Number.isFinite(us) && us >= 0) out.outTimeSec = us / 1_000_000;
+    } else if (key === "out_time") {
+      const m = /^(\d+):(\d{1,2}):(\d{1,2}(?:\.\d+)?)$/.exec(value);
+      if (m !== null) {
+        out.outTimeSec = Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]);
+      }
+    } else if (key === "speed") {
+      const n = Number(value.replace(/x$/i, ""));
+      if (Number.isFinite(n) && n >= 0) out.speed = n;
+    }
+  }
+  return out;
+}
+
+/**
+ * Seconds of encode left: (duration − done) / speed. Null when speed ≤ 0 —
+ * a division by ffmpeg's warm-up `speed=0x` would print "Infinity left".
+ * Clamped at 0: out_time can overshoot the probed duration at the tail
+ * (muxer flush), and a negative ETA reads as nonsense.
+ */
+export function encodeEta(durationSec: number, outTimeSec: number, speed: number): number | null {
+  if (speed <= 0) return null;
+  return Math.max(0, (durationSec - outTimeSec) / speed);
+}
+
+/**
+ * Seconds → "5:20". Lived in the CLI's publish.ts first (duration-cap
+ * messages); moved here so the progress lines on both sides of the wire spell
+ * time the same way — the CLI re-exports it, the panel keeps its own copy for
+ * the documented Vite-bundle reason.
+ */
+export function formatMinSec(sec: number): string {
+  const whole = Math.round(sec);
+  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}

package/src/publish/provider.ts

@@ -0,0 +1,81 @@
+/**
+ * The one seam between ossclip and any social-publishing backend, mirroring
+ * `producer/provider.ts`: no backend types leak past this interface (the
+ * PHASE1 §4 posture, applied to publishing). One implementation today —
+ * Postiz (`postiz.ts`) — but the CLI, the edit server and the tests all
+ * speak this shape, so a direct per-platform adapter later is a new file,
+ * not a rewrite.
+ */
+
+/** One connected account at the backend — an "integration" in Postiz terms. */
+export interface PublishTarget {
+  /** The backend's own id for the connected account. */
+  id: string;
+  /** The platform identifier the backend reports, e.g. "linkedin", "x". */
+  provider: string;
+  /** Human-readable account name, for pickers and receipts. */
+  name: string;
+}
+
+export type PublishWhen = { kind: "now" } | { kind: "at"; iso: string };
+
+export interface PublishPost {
+  target: PublishTarget;
+  caption: string;
+  /**
+   * Some platforms carry a title separate from the caption (YouTube).
+   * Optional — most don't.
+   */
+  title?: string;
+  /**
+   * YouTube's privacy status — REQUIRED by Postiz's own DTO (`type`,
+   * @IsDefined), so a YouTube post without it fails validation and takes the
+   * whole /posts call with it (2026-08-28). Optional here because only
+   * YouTube has the concept; `buildPostsPayload` supplies the default.
+   */
+  youtubePrivacy?: "public" | "unlisted" | "private";
+  /**
+   * This post's media, when it must differ from the request's default
+   * `videoPath`. Size-capped platforms are the reason it exists (2026-08-29,
+   * live: Instagram bounced the 409MB delivery file with 2207077 but
+   * published the 88MB re-encode — `PLATFORM_SIZE_CAP_BYTES`): they carry
+   * their own smaller encode while everyone else keeps the 10 Mbps file.
+   * Each distinct file uploads once; posts map to their media.
+   */
+  videoPath?: string;
+}
+
+export interface PublishRequest {
+  /**
+   * Absolute path of the default media — the delivery encode, or the master
+   * when none is needed (`ensureDeliveryFile`). A post whose platform needs
+   * a different file sets its own `PublishPost.videoPath`; the provider
+   * uploads each distinct file once and maps posts to their media. Sending
+   * the MASTER to YouTube via that mechanism remains the noted follow-up
+   * (2026-08-29 plan).
+   */
+  videoPath: string;
+  posts: PublishPost[];
+  when: PublishWhen;
+}
+
+/**
+ * What `publish()` returns AND what `<workdir>/publish-receipt.json` holds —
+ * the double-post guard reads this file, so it records enough to tell the
+ * user what already went out, and when.
+ */
+export interface PublishReceipt {
+  backend: string;
+  /** Backend post ids, when the backend reports them; may be empty. */
+  postIds: string[];
+  /** ISO time the publish request was accepted (not the scheduled time). */
+  publishedAt: string;
+  when: PublishWhen;
+  targets: PublishTarget[];
+}
+
+export interface PublishProvider {
+  readonly name: string;
+  listTargets(): Promise<PublishTarget[]>;
+  publish(req: PublishRequest): Promise<PublishReceipt>;
+}

package/src/recut.ts

@@ -1,4 +1,4 @@
-import { SPLIT_MIN_PIECE_SEC, type OverrideDoc } from "./overrides";
+import { isSrcTiming, SPLIT_MIN_PIECE_SEC, type OverrideDoc } from "./overrides";
 import type { Segment } from "./schema";
 import { mapsClose, TimeMap } from "./timemap";
 
@@ -65,8 +65,16 @@ export function remapOverridesThroughRecut(
   // (§137, `SplitSchema`) — re-deriving it here is what renamed the half and
   // orphaned the overrides on it.
   const splits = doc.splits.map((s) => {
+    // A src-anchored split passes through UNTOUCHED — the `doc.cuts`
+    // non-remap rule below, for the same reason `cleanup.kept` needs no
+    // entry here at all: source time is stable across every re-cut, and
+    // `resolveSplitPoints` re-derives the output instant fresh at each
+    // application. Only the src-less legacy shape still carries an
+    // old-clock `at` worth moving.
+    if (s.src !== undefined) return s;
     const before = reports.length;
-    const at = remapPoint(`split "${s.id}"`, s.at, oldMap, newMap, reports);
+    const atBefore = s.at!;
+    const at = remapPoint(`split "${s.id}"`, atBefore, oldMap, newMap, reports);
     // `splitCues` needs a cue with `at >= startSec + SPLIT_MIN_PIECE_SEC` AND
     // `at <= endSec - SPLIT_MIN_PIECE_SEC`. Output time runs [0,
     // outputDuration] and every cue lives inside it, so a split closer than
@@ -101,7 +109,7 @@ export function remapOverridesThroughRecut(
     // a cut edge; restating it here would read as a second, separate move
     // rather than the consequence of the one already reported.
     const where = reports.length > before ? "is" : `is now ${at.toFixed(3)}s —`;
-    if (at < SPLIT_MIN_PIECE_SEC && s.at >= SPLIT_MIN_PIECE_SEC) {
+    if (at < SPLIT_MIN_PIECE_SEC && atBefore >= SPLIT_MIN_PIECE_SEC) {
       reports.push(
         `split "${s.id}" ${where} too close to the start to divide a scene, ` +
           `so any edit on its second half will not apply`,
@@ -111,7 +119,7 @@ export function remapOverridesThroughRecut(
       // no longer divide anything — two would read as two problems.
     } else if (
       at > newMap.outputDuration - SPLIT_MIN_PIECE_SEC &&
-      s.at <= oldMap.outputDuration - SPLIT_MIN_PIECE_SEC
+      atBefore <= oldMap.outputDuration - SPLIT_MIN_PIECE_SEC
     ) {
       reports.push(
         `split "${s.id}" ${where} too close to the end to divide a scene, ` +
@@ -128,6 +136,14 @@ export function remapOverridesThroughRecut(
   const scenes = Object.fromEntries(
     Object.entries(doc.scenes).map(([id, scene]) => {
       if (!scene.timing) return [id, scene];
+      // A SRC-anchored pin is not remapped, for the same reason `cuts` below
+      // and `cleanup.kept` are not: source seconds are the one clock a re-cut
+      // cannot move, so re-anchoring one could only ever corrupt it — and a
+      // pin inside material THIS re-cut removed has no image on the new
+      // clock at all, which `remapPoint` would answer by clamping it onto
+      // the seam instead of leaving it inert (`resolveTimingPin` is where
+      // that verdict belongs). Legacy old-clock pins keep the remap verbatim.
+      if (isSrcTiming(scene.timing)) return [id, scene];
       const startSec = remapPoint(`"${id}" pinned start`, scene.timing.startSec, oldMap, newMap, reports);
       const endSec = remapPoint(`"${id}" pinned end`, scene.timing.endSec, oldMap, newMap, reports);
       return [id, { ...scene, timing: { startSec, endSec } }];

package/src/resolution.ts

@@ -0,0 +1,114 @@
+import { z } from "zod/v4";
+
+/**
+ * How big the output actually renders (2026-08-27).
+ *
+ * ossclip rendered 1080×1920 unconditionally, and three separate stages
+ * enforced it: the folder-concat target, the mezzanine's scale filter, and
+ * the render. A 4K take therefore lost three quarters of its pixels before
+ * anything looked at it — invisible on LinkedIn/Instagram/TikTok, which cap
+ * at 1080p anyway, but real on YouTube, which keeps 4K and gives it a better
+ * codec tier.
+ *
+ * This is the ONE place that decides the size, so those three stages cannot
+ * disagree. It returns a SCALE FACTOR, not a stage to build from: the
+ * composition must stay 1080-wide because `captionFontSizeFor` (scenes/
+ * stage.ts) answers in ABSOLUTE px — 64 portrait, 44 landscape — so a
+ * composition built at 2160 would draw captions a quarter of their intended
+ * size. Remotion's own `scale` renders that same composition larger, fonts
+ * and strokes included.
+ */
+
+/** `--resolution`: an explicit short-edge height, or `auto` from the source. */
+export const RESOLUTION_CHOICES = ["auto", "1080", "1440", "2160"] as const;
+
+export type ResolutionChoice = (typeof RESOLUTION_CHOICES)[number];
+
+/** The gate every user-supplied resolution passes through — flag AND config,
+ * so a hand-edited `"resolution": "4k"` earns the same refusal as a typo'd
+ * flag rather than a silent fallback (CLAUDE.md: parse, never coerce). */
+export const ResolutionChoiceSchema = z.enum(RESOLUTION_CHOICES);
+
+/**
+ * The ceiling `auto` will not cross, as a short-edge height. An 8K source
+ * answers 2160 rather than 4320: h264 at 8K is not universally playable, and
+ * the render cost grows with the pixel count.
+ */
+export const MAX_AUTO_HEIGHT = 2160;
+
+/** The base short edge both frames share — the unit every choice divides by. */
+const BASE_SHORT_EDGE = 1080;
+
+/**
+ * `auto` snaps DOWN to a half step (1, 1.5, 2). Two reasons, both hard:
+ * h264 needs EVEN dimensions, and 1080/1920 times a half step is always even
+ * while an arbitrary factor is not (1.125 → 1215, odd); and rounding odd
+ * dimensions to even would drift the frame off 9:16, which the platforms
+ * letterbox. Snapping down rather than up keeps the promise that auto never
+ * invents detail the source does not have.
+ */
+const AUTO_STEP = 0.5;
+
+export interface OutputFrame {
+  /** What Remotion renders the 1080-wide composition at. */
+  scale: number;
+  /** The resulting file's dimensions — what `production.json` records. */
+  width: number;
+  height: number;
+}
+
+/**
+ * The clip a FOLDER input can honestly be sized by: the smallest.
+ *
+ * A folder concat letterboxes every take into one frame (`buildConcatFilter`),
+ * so the frame carries only what the weakest clip has — sizing by the largest
+ * would upscale every other take and charge render time for invented pixels.
+ * Clips that failed to probe are ignored rather than counted as zero, and a
+ * listing with nothing usable answers `null` so the caller falls back to its
+ * default instead of sizing a render off a guess.
+ */
+export function smallestSource(
+  sizes: ReadonlyArray<{ width: number; height: number }>,
+): { width: number; height: number } | null {
+  const usable = sizes.filter((s) => s.width > 0 && s.height > 0);
+  if (usable.length === 0) return null;
+  return usable.reduce((min, s) => (s.width * s.height < min.width * min.height ? s : min));
+}
+
+export function resolveOutputFrame(args: {
+  frame: { width: number; height: number };
+  /** The source's DISPLAY dimensions (rotation already applied by the probe). */
+  source: { width: number; height: number };
+  resolution: ResolutionChoice;
+}): OutputFrame {
+  const { frame, source, resolution } = args;
+  const at = (scale: number): OutputFrame => ({
+    scale,
+    width: Math.round(frame.width * scale),
+    height: Math.round(frame.height * scale),
+  });
+  if (resolution !== "auto") {
+    return at(Number(resolution) / BASE_SHORT_EDGE);
+  }
+  // A probe that answered nothing cannot size anything: today's 1080p is the
+  // honest fallback, never a throw in the middle of a render.
+  if (!(source.width > 0) || !(source.height > 0)) return at(1);
+
+  // The pixels that SURVIVE the crop, not the ones the file advertises. The
+  // source is fitted to the output's aspect and the overflow is cropped
+  // (produce's own `force_original_aspect_ratio=increase,crop=`), so the
+  // usable width is whichever edge binds.
+  const frameAspect = frame.width / frame.height;
+  const sourceAspect = source.width / source.height;
+  const usableWidth =
+    sourceAspect > frameAspect
+      ? source.height * frameAspect // wider than the frame: sides are cropped
+      : source.width; //               taller than the frame: top/bottom cropped
+
+  const raw = usableWidth / frame.width;
+  const snapped = Math.floor(raw / AUTO_STEP) * AUTO_STEP;
+  const capped = Math.min(snapped, MAX_AUTO_HEIGHT / BASE_SHORT_EDGE);
+  // Never below today's output: a 720p source still renders 1080p, which is
+  // what every caller already depends on.
+  return at(Math.max(capped, 1));
+}