@sprid/cli 0.1.2

package/src/post/recipes/screen.mjs

@@ -0,0 +1,290 @@
+// The `screen` recipe: an app, driven, recorded, and cut into a reel.
+//
+// **The thing it exists for is the seven-language version.** A demo reel is
+// expensive to make once and usually impossible to make again in another
+// language, because the work is a person holding a phone. Here the work splits
+// in two: a SCRIPT, which is the finger's path through the app and carries no
+// words at all, and a SPEC, which carries the locale and the captions. Running
+// the same script under a different locale is one command and about ninety
+// seconds, so a language costs what its translation costs and nothing else.
+//
+//   social/scripts/log-a-decision.json     the path. one file, all languages.
+//   social/specs/log-a-decision-sv.json    the locale, the captions, the music.
+//
+// Everything below is a default, and the recipe prints the ffmpeg command it
+// ran. See `src/screen/` for the three halves: the simulator, the caption
+// timing, the graph.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  boot, clapper, clearStatusBar, clearStuckRecorder, deviceRect, deviceSize, dressStatusBar,
+  kit, readJson, resolveDevice, runScript, simkit, sleep, startRecording, writeJson,
+} from "../screen/sim.mjs";
+import { settle as settleFor } from "../screen/sim.mjs";
+import { layout } from "../screen/captions.mjs";
+import { hasBaguette, openInput } from "../screen/input.mjs";
+import {
+  H, W, FPS, audioChain, buildGraph, driftExpr, encodeBroll, findClappers,
+  renderCaptions, run, solveClock,
+} from "../screen/compose.mjs";
+
+const FONT_CANDIDATES = [
+  `${process.env.HOME}/Library/Fonts/TikTokSans-Bold.ttf`,
+  `${process.env.HOME}/Library/Fonts/DMSans-Bold.ttf`,
+  "/System/Library/Fonts/SFNS.ttf",
+];
+
+/**
+ * `recut` re-cuts the recording already in `tmp` and touches no simulator at
+ * all. **It is the loop that matters.** Driving the app takes the machine's
+ * pointer for a minute and a half, and almost everything you iterate on after
+ * the first run - a caption, a beat, where the captions sit, the speed, the
+ * drift - does not need the app driven again. `cut.json` holds exactly what a
+ * re-cut needs: the timeline, the second clapper's wall time, and the device's
+ * pixel size.
+ */
+export async function buildScreen({ spec, script, root, out, tmp, recut = false, log = console.log }) {
+  const cfg = {
+    device: "iPhone 17",
+    fill: 1.0,             // how much of the 1920 the phone takes
+    capY: 0.72,            // the caption baseline, as a fraction of the frame
+    capSize: 82,
+    // **Off.** A screen recording holds still. An earlier default drifted the
+    // phone a few pixels on two sine pairs to imitate a hand, and it reads as
+    // the wrong thing entirely: nobody believes a hand is holding a frame whose
+    // status bar is pin-sharp, so the movement registers as the video being
+    // unstable rather than as being filmed. Set `render.drift` to a small
+    // number (4-6px) only if a specific cut actually wants it.
+    drift: 0,
+    dot: 108,
+    speed: 1,
+    background: "blur",
+    tailMs: 900,
+    leadMs: 250,
+    crf: 19,
+    ...spec.render,
+  };
+  mkdirSync(tmp, { recursive: true });
+  const advice0 = [];
+  const bin = simkit();
+  const raw = join(tmp, "raw.mov");
+  const cutPath = join(tmp, "cut.json");
+
+  let timeline;
+  /** Wall ms from the first clapper flash to the second. */
+  let endClapAt;
+  /** The device screen in pixels; it sets the reel's geometry. */
+  let px;
+
+  if (recut) {
+    if (!existsSync(cutPath) || !existsSync(raw))
+      throw new Error(
+        `Nothing to re-cut for ${spec.slug}: both cut.json and raw.mov have to be in ${tmp} from a ` +
+          "previous run. Build it once without --recut.",
+      );
+    const cut = JSON.parse(readFileSync(cutPath, "utf8"));
+    ({ timeline, endClapAt, px } = cut);
+    log(`  recut   the recording from ${cut.at} - no simulator`);
+  } else {
+    // ---- the device -------------------------------------------------------
+    const udid = resolveDevice(spec.device ?? cfg.device);
+    log(`  device  ${spec.device ?? cfg.device}  ${udid}`);
+    boot(udid);
+    dressStatusBar(udid, { time: spec.statusBarTime ?? "now", ...(spec.battery ? { battery: spec.battery } : {}) });
+
+    // ---- the repo's own preparation ---------------------------------------
+    // **This is the boundary.** Metro, the demo seed, the locale, the install:
+    // all of it is welded to the consuming repo and none of it belongs in a
+    // package. The recipe asks for a command and waits for it to exit 0.
+    if (spec.app?.prepare) {
+      const cmd = spec.app.prepare.replaceAll("<locale>", spec.locale ?? "en").replaceAll("<udid>", udid);
+      log(`  prepare ${cmd}`);
+      const r = spawnSync("/bin/sh", ["-c", cmd], { cwd: root, stdio: "inherit" });
+      if (r.status !== 0) throw new Error("prepare failed");
+    }
+
+    px = deviceSize(udid, tmp);
+    log(`  screen  ${px.w}x${px.h}px`);
+    // **The window geometry is only the CGEvent fallback's problem.** baguette
+    // scales by the width/height it is given, so with it there is nothing to
+    // calibrate and resizing the Simulator window cannot break a run.
+    const input = openInput({
+      udid, px, kit,
+      rect: hasBaguette() && spec.input !== "cgevent" ? undefined : deviceRect(px.w / px.h),
+      backend: spec.input, log,
+    });
+
+    // ---- record -----------------------------------------------------------
+    let rec = startRecording(udid, raw);
+    try {
+      await rec.ready();
+    } catch (e) {
+      // An interrupted run poisons the next one, and it is not the next run's
+      // fault - recover once rather than making a person read the error.
+      if (!/already in progress/i.test(String(e))) throw e;
+      log("  record  the last run left the recorder registered; cycling the device");
+      await rec.stop();
+      await clearStuckRecorder(udid);
+      dressStatusBar(udid, { time: spec.statusBarTime ?? "now", ...(spec.battery ? { battery: spec.battery } : {}) });
+      rec = startRecording(udid, raw);
+      await rec.ready();
+    }
+    const clapAt = await clapper(udid, { bundleId: spec.app?.bundleId });   // the timeline's zero
+    try {
+      // **The launch is the recipe's, not the repo's.** The anchor above has to
+      // happen on the springboard, so the app comes up after it - which means
+      // `prepare` seeds and configures and stops short of launching.
+      if (spec.app?.bundleId) {
+        spawnSync("xcrun", ["simctl", "launch", udid, spec.app.bundleId], { stdio: "ignore" });
+        await sleep(spec.app.launchMs ?? 18_000);
+        await settleFor(udid, tmp, { maxMs: 6000 });
+      }
+      timeline = await runScript(script, {
+        udid, tmp, input, t0: clapAt, root, log,
+        vars: { udid, locale: spec.locale ?? "en", bundleId: spec.app?.bundleId ?? "" },
+      });
+      await sleep(cfg.tailMs);
+      // The second anchor. It happens after everything the reel keeps, so the
+      // terminate it needs costs nothing.
+      endClapAt = (await clapper(udid, { bundleId: spec.app?.bundleId })) - clapAt;
+    } finally {
+      input.close();
+      await rec.stop();
+      clearStatusBar(udid);
+    }
+    writeJson(join(tmp, "timeline.json"), timeline);
+    // Everything a re-cut needs and nothing it does not. `endClapAt` above all:
+    // without the second clapper's wall time the recorder's clock cannot be
+    // solved from the video alone, and a re-cut would have to guess it.
+    writeJson(cutPath, {
+      at: new Date().toISOString(), device: spec.device ?? cfg.device, px, endClapAt, timeline,
+    });
+  }
+
+  // ---- solve the recorder's clock -----------------------------------------
+  const plateaus = findClappers(raw);
+  const clock = solveClock(plateaus, 0, endClapAt);
+  if (!clock)
+    throw new Error(`Found ${plateaus.length} clapper flash(es) in the recording, needed 2. ` +
+      "The flash is the springboard going dark, so this means the app was still in front of it - " +
+      "check that `app.bundleId` is right and that `prepare` passes --no-launch.");
+  log(`  clock   flashes at ${clock.first.toFixed(2)}s and ${clock.last.toFixed(2)}s; ` +
+    `the recorder runs at ${clock.k.toFixed(4)}x wall`);
+  // **A low k is a spoiled recording, not a number to correct for.** The solve
+  // keeps the captions in sync, but the missing time cannot be put back: at
+  // 0.71 the app's own motion plays 1.4x fast on top of whatever `speed` asked
+  // for. It happens when the machine is loaded enough to starve the recorder.
+  if (clock.k < 0.9)
+    throw new Error(
+      `The recorder held only ${(clock.k * 100).toFixed(0)}% of the elapsed time, so the app's motion in this ` +
+        `take plays ${(1 / clock.k).toFixed(2)}x fast. That is a spoiled recording rather than something to ` +
+        "correct for - run it again on a quieter machine.",
+    );
+  if (clock.k > 1.1)
+    advice0.push(`The recording clock solved to ${clock.k.toFixed(3)}x wall, which is too far off to trust. Check the two flashes.`);
+  const toVideo = (ms) => clock.v0 + clock.k * ms / 1000;
+
+  // ---- when the reel starts and stops -------------------------------------
+  // **The reel starts at a mark, not at a step.** The first thing a viewer sees
+  // has to be the screen the hook is about, and that screen is on-camera for a
+  // beat before anything is tapped - so the in-point is the script's first mark
+  // (or whichever `startAt` names), never "the first gesture minus 250ms".
+  const firstMark = Object.entries(timeline.marks).sort((a, b) => a[1] - b[1])[0];
+  const firstStep = timeline.steps.find((s) => s.kind !== "wait") ?? timeline.steps[0];
+  const startMs = spec.startMs
+    ?? (spec.startAt ? timeline.marks[spec.startAt] : firstMark?.[1])
+    ?? Math.max(0, (firstStep?.t ?? 0) - cfg.leadMs);
+  const endMs = spec.endMs ?? timeline.endedAt + cfg.tailMs;
+  const durationMs = ((toVideo(endMs) - toVideo(startMs)) * 1000) / cfg.speed;
+  const seconds = durationMs / 1000;
+  log(`  length  ${seconds.toFixed(1)}s${cfg.speed !== 1 ? ` (at ${cfg.speed}x)` : ""}`);
+
+  const advice = [...advice0];
+  const brollSeconds = spec.broll ? (spec.broll.seconds ?? 2.4) : 0;
+  const total = seconds + brollSeconds;
+  if (total > 20) advice.push(`${total.toFixed(1)}s is long. 15-17s is the only length either account has a number behind it; trim the script or raise \`render.speed\`.`);
+  if (total < 8) advice.push(`${total.toFixed(1)}s is very short - under about 8s there is no watch time to earn.`);
+
+  // ---- captions -----------------------------------------------------------
+  // Wall milliseconds -> milliseconds in the finished reel. Both corrections
+  // in one line: the recorder's rate, then the speed-up.
+  const shift = (t) => ((toVideo(t) - toVideo(startMs)) * 1000) / cfg.speed;
+  const marks = Object.fromEntries(Object.entries(timeline.marks).map(([k, v]) => [k, shift(v)]));
+  const { cards, warnings } = layout(spec.captions ?? [], marks, durationMs, { locale: spec.locale ?? "en" });
+  advice.push(...warnings);
+
+  const fontFile = spec.render?.fontFile
+    ? resolve(root, spec.render.fontFile)
+    : FONT_CANDIDATES.find(existsSync);
+  const rendered = renderCaptions(cards, {
+    simkitBin: bin, dir: join(tmp, "captions"), fontFile,
+    size: cfg.capSize, width: Math.round(W * 0.88), pill: cfg.pill ?? 0,
+    ...(cfg.stroke != null ? { stroke: cfg.stroke } : {}),
+  });
+
+  const dotPng = join(tmp, "dot.png");
+  spawnSync(bin, ["dot", "--out", dotPng, "--r", String(cfg.dot / 2)]);
+
+  // ---- geometry -----------------------------------------------------------
+  const fh = H * cfg.fill;
+  const fw = fh * (px.w / px.h);
+  const geom = { fx: (W - fw) / 2, fy: (H - fh) / 2, fw, fh };
+  const drift = driftExpr(cfg.drift);
+
+  const gestures = timeline.gestures.map((g) => ({ ...g, t: shift(g.t), durationMs: (g.durationMs * clock.k) / cfg.speed }));
+
+  const graph = buildGraph({
+    cards: rendered, gestures, geom, drift, videoOffsetMs: 0,
+    dotSize: cfg.dot, capY: H * cfg.capY, background: cfg.background,
+    trimStart: toVideo(startMs), duration: toVideo(endMs) - toVideo(startMs), speed: cfg.speed,
+  });
+
+  // ---- the graph ----------------------------------------------------------
+  const screenOnly = join(tmp, "screen.mp4");
+  const args = ["-y", "-i", raw, "-i", dotPng, ...rendered.flatMap((c) => ["-i", c.png])];
+  let filter = graph;
+  const trackPath = spec.track ? resolve(root, spec.track) : null;
+
+  // Music covers the b-roll too, so it is laid over the concatenated file when
+  // there is b-roll and over this one when there is not.
+  if (trackPath && !spec.broll) {
+    args.push("-i", trackPath);
+    filter += ";" + audioChain(2 + rendered.length, trackPath, seconds);
+  }
+  args.push("-filter_complex", filter, "-map", "[vout]");
+  if (trackPath && !spec.broll) args.push("-map", "[aout]", "-c:a", "aac", "-b:a", "192k");
+  else args.push("-an");
+  args.push("-r", String(FPS), "-c:v", "libx264", "-crf", String(cfg.crf), "-preset", "medium",
+    "-pix_fmt", "yuv420p", "-movflags", "+faststart", screenOnly);
+
+  const printed = `ffmpeg ${args.map((a) => (/[ ;'"\[\]]/.test(a) ? `'${a.replaceAll("'", "'\\''")}'` : a)).join(" ")}`;
+  const r = run(args);
+  if (r.status !== 0) throw new Error(`ffmpeg failed:\n${r.stderr.slice(-2500)}`);
+
+  // ---- b-roll -------------------------------------------------------------
+  mkdirSync(dirname(out), { recursive: true });
+  if (!spec.broll) {
+    spawnSync("/bin/cp", [screenOnly, out]);
+  } else {
+    const head = encodeBroll(resolve(root, spec.broll.clip), {
+      out: join(tmp, "broll.mp4"), seconds: brollSeconds, ss: spec.broll.ss ?? 0, crf: cfg.crf,
+    });
+    const silent = join(tmp, "joined.mp4");
+    const listFile = join(tmp, "concat.txt");
+    writeFileSync(listFile, `file '${head}'\nfile '${screenOnly}'\n`);
+    const j = run(["-y", "-f", "concat", "-safe", "0", "-i", listFile, "-c", "copy", "-movflags", "+faststart", silent]);
+    if (j.status !== 0) throw new Error(`concat failed:\n${j.stderr.slice(-1500)}`);
+    if (trackPath) {
+      const a = run(["-y", "-i", silent, "-i", trackPath, "-filter_complex", audioChain(1, trackPath, total),
+        "-map", "0:v", "-map", "[aout]", "-c:v", "copy", "-c:a", "aac", "-b:a", "192k",
+        "-movflags", "+faststart", out]);
+      if (a.status !== 0) throw new Error(`music failed:\n${a.stderr.slice(-1500)}`);
+    } else spawnSync("/bin/cp", [silent, out]);
+  }
+
+  const commandPath = join(tmp, "ffmpeg-command.txt");
+  writeFileSync(commandPath, printed + "\n");
+  return { command: printed, commandPath, advice, timeline, cards: rendered, seconds: total };
+}

package/src/post/recipes/stills.mjs

@@ -0,0 +1,146 @@
+// The one built-in recipe: photographs into a moving reel.
+//
+// **It answers the thing nothing else does** - material that is neither text
+// nor already a video. Text reels are composed in Sprid, where the templates
+// live; a file you already have goes straight into the media picker. What has
+// no home is a folder of pictures.
+//
+// It is a RECIPE and not a framework, which means one thing in practice: it
+// prints the ffmpeg command it ran. The output is a starting point somebody
+// edits, not a black box. Everything below is a default, and every default is
+// either measured or copied from a pipeline that measured it.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+
+/** 9:16, which is the only shape a reel is. */
+const W = 1080;
+const H = 1920;
+const FPS = 30;
+
+/**
+ * Loudness of the EXCERPT, not the file.
+ *
+ * A bed's integrated loudness is not its opening fifteen seconds', and mixing
+ * those two up is the single most expensive audio mistake in either pipeline
+ * this recipe was drawn from: measuring the master put one lane's batch at 3.8
+ * LUFS spread - audible between two posts in a row - while the lane that
+ * measured its window sat at 1.5.
+ */
+function measureLufs(path, seconds) {
+  const r = spawnSync(
+    "ffmpeg",
+    ["-hide_banner", "-nostats", "-t", seconds.toFixed(3), "-i", path, "-filter:a", "loudnorm=print_format=json", "-f", "null", "-"],
+    { encoding: "utf8" },
+  );
+  const m = /"input_i"\s*:\s*"(-?[\d.]+)"/.exec(r.stderr ?? "");
+  if (!m) throw new Error(`Could not measure loudness of ${path} - is it an audio file?`);
+  return Number(m[1]);
+}
+
+/**
+ * The moving image.
+ *
+ * **Scaled up before the push, then back down.** `zoompan` positions on whole
+ * source pixels, so pushing a 1080-wide image directly makes the frame step
+ * rather than glide - the same judder that makes a slow pan look like a
+ * slideshow. Working at 2x and landing at 1080 puts the step under half an
+ * output pixel.
+ *
+ * The push is small on purpose. 6% over three seconds reads as the camera
+ * breathing; anything you can see moving is a zoom, and a zoom draws attention
+ * to the tool rather than the picture.
+ */
+function imageChain(i, holdMs, push) {
+  const frames = Math.round((holdMs / 1000) * FPS);
+  const per = (push - 1) / frames;
+  return (
+    `[${i}:v]scale=${W * 2}:${H * 2}:force_original_aspect_ratio=increase,` +
+    `crop=${W * 2}:${H * 2},` +
+    `zoompan=z='min(1+${per.toFixed(6)}*on,${push})':d=${frames}` +
+    `:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=${W}x${H}:fps=${FPS},` +
+    `setsar=1,format=yuv420p[v${i}]`
+  );
+}
+
+export function buildStills({
+  images,
+  track,
+  out,
+  holdMs = 3000,
+  xfadeMs = 600,
+  push = 1.06,
+  targetLufs = -14,
+  crf = 20,
+}) {
+  if (!images?.length) throw new Error("stills needs at least one image (`--in <folder>` or a spec with `images`).");
+  for (const f of images) if (!existsSync(f)) throw new Error(`No such image: ${f}`);
+  if (track && !existsSync(track)) throw new Error(`No such track: ${track}`);
+
+  // Each card overlaps the one before it by the fade, so the reel is shorter
+  // than the sum of its holds. Getting this wrong is what makes a reel end on
+  // a frozen frame.
+  const totalMs = images.length * holdMs - (images.length - 1) * xfadeMs;
+  const total = totalMs / 1000;
+
+  // **15-17 seconds.** The one number worth being opinionated about, because it
+  // is the only one with a measurement behind it: a batch cut to 15.5s drew
+  // 113-162 views against 6-22 for the same account's 29-32s cuts. Said once,
+  // as advice, and then the render proceeds - it is the customer's reel.
+  const advice = [];
+  if (total > 20) advice.push(`${total.toFixed(1)}s is long for a reel. 15-17s is the only length with a number behind it; try --hold ${Math.floor((17000 + (images.length - 1) * xfadeMs) / images.length / 100) * 100}.`);
+  if (total < 8) advice.push(`${total.toFixed(1)}s is very short. Under about 8s there is no watch time to earn.`);
+
+  const parts = images.map((_, i) => imageChain(i, holdMs, push));
+
+  // xfade chains pairwise, and each offset is measured from the start of the
+  // CHAIN so far, not from the clip - the classic way to get a reel that
+  // dissolves correctly for two cards and then drifts.
+  let last = "v0";
+  for (let i = 1; i < images.length; i++) {
+    const offset = (holdMs * i - xfadeMs * i) / 1000;
+    const label = i === images.length - 1 ? "vout" : `x${i}`;
+    parts.push(`[${last}][v${i}]xfade=transition=fade:duration=${(xfadeMs / 1000).toFixed(3)}:offset=${offset.toFixed(3)}[${label}]`);
+    last = label;
+  }
+  if (images.length === 1) parts.push(`[v0]copy[vout]`);
+
+  const args = ["-y"];
+  for (const f of images) args.push("-loop", "1", "-t", (holdMs / 1000).toFixed(3), "-i", f);
+
+  if (track) {
+    args.push("-i", track);
+    const gain = targetLufs - measureLufs(track, total);
+    parts.push(
+      `[${images.length}:a]atrim=start=0:end=${total.toFixed(3)},asetpts=PTS-STARTPTS,` +
+        `volume=${gain.toFixed(2)}dB,` +
+        // -3 dBFS, not -1.5. The AAC encode overshoots the limiter: a -1.5
+        // ceiling came back out of the mp4 at 0.0 dB with clipped samples.
+        `alimiter=limit=0.708:level=disabled,` +
+        `afade=t=in:st=0:d=0.4,afade=t=out:st=${Math.max(0, total - 1.2).toFixed(3)}:d=1.2[aout]`,
+    );
+  }
+
+  args.push("-filter_complex", parts.join(";"), "-map", "[vout]");
+  if (track) args.push("-map", "[aout]", "-c:a", "aac", "-b:a", "192k");
+  args.push(
+    "-t", total.toFixed(3),
+    "-r", String(FPS),
+    "-c:v", "libx264", "-preset", "medium", "-crf", String(crf),
+    "-pix_fmt", "yuv420p", "-movflags", "+faststart",
+    out,
+  );
+
+  const r = spawnSync("ffmpeg", ["-loglevel", "error", ...args], { encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`ffmpeg failed:\n${(r.stderr ?? "").split("\n").slice(-6).join("\n")}`);
+
+  return {
+    out,
+    durationMs: totalMs,
+    sizeBytes: statSync(out).size,
+    advice,
+    // Printed by the caller. This is the whole difference between a recipe and
+    // a framework: what it did is a command you can take and change.
+    command: `ffmpeg ${args.map((a) => (/[\s;'"\[\]]/.test(a) ? `'${a}'` : a)).join(" ")}`,
+  };
+}

package/src/post/rules/platform-rules.d.mts

@@ -0,0 +1,27 @@
+/** Types for the dependency-free publishing projection shared by CLI and API. */
+export interface PostProjectionInput {
+  internalName?: string | null;
+  title?: string | null;
+  captionInstagram?: string | null;
+  captionTiktok?: string | null;
+  instagramLocationId?: string | null;
+  platforms?: readonly string[];
+  pinterestOptions?: { boardId?: string; title?: string; description?: string; link?: string; altText?: string };
+  options?: {
+    youtube?: { title?: string };
+    pinterest?: { boardId?: string; title?: string; description?: string; link?: string; altText?: string };
+  };
+}
+
+export interface PlatformProjection {
+  platform: string;
+  title: string | null;
+  body: string;
+  problems: string[];
+}
+
+export function projectPost(post: PostProjectionInput): PlatformProjection[];
+export function looksLikeSlug(value: string): boolean;
+export function internalTitleProblem(value: string): string | null;
+export function projectYoutubeTitle(input?: { title?: string | null; caption?: string | null; options?: { title?: string } }): { title: string; problems: string[] };
+export function youtubeTitle(raw: string, options?: { shortsTag?: boolean }): string;

package/src/post/rules/platform-rules.mjs

@@ -0,0 +1,164 @@
+// What each platform will actually publish, computed in one place.
+//
+// **Plain .mjs with no imports, because `sprid` ships with zero dependencies.**
+// These rules have to be readable by the CLI (which has no build step and must
+// stay dependency-free) and by the publish adapters on the server. Anything
+// that lived only in the server's shared package would drag an image pipeline,
+// an ORM and a storage SDK into a command line; anything that lived only in the
+// CLI would be a second copy of the rules the publisher actually runs. So this
+// file is the source, and the server re-exports it.
+//
+// **One post is several posts, and every platform reads a different field.**
+// Instagram takes the caption and a cover; TikTok takes the caption AND the
+// post's title as its in-app title; YouTube takes the title for the Short and
+// the caption for the description. Validate the fields each destination reads.
+//
+// This is the answer to "what goes out, exactly". It is deliberately a pure
+// function of a post so it can serve an endpoint, a CLI gate and an editor
+// preview from the same rules - a second implementation anywhere else drifts
+// from the adapters and ends up agreeing with the bug.
+
+
+/** TikTok truncates its in-app title at 90 UTF-16 chars. */
+const TIKTOK_TITLE_MAX = 90;
+
+/**
+ * Does this string look like an identifier rather than something written?
+ *
+ * Three or more lowercase hyphen-joined segments with no spaces are treated
+ * as an identifier. Supply a display title or omit this check when that spelling is intentional.
+ */
+export function looksLikeSlug(s) {
+  return /^[a-z0-9]+(-[a-z0-9]+){2,}$/.test(s.trim());
+}
+
+/** Production labels and source annotations must never become public titles. */
+export function internalTitleProblem(raw) {
+  const title = raw.trim().split("\n")[0].trim();
+  if (/^(?:reel(?:\s+r\d+(?:-[a-z]+)?)?|scripts?|signs|bingo)\s*:/i.test(title) ||
+      /^reel\s+r\d+(?:-[a-z]+)?(?:\s|$)/i.test(title) ||
+      /\((?:guide|guides|voc|gsc|scripts?|bingo|relatability|from\s+\d+|\d+\s+re-cut)\b/i.test(title) ||
+      /^\[asset bake\]/i.test(title)) {
+    return 'YouTube title contains an internal production label or source note. Set a viewer-facing post title or options.youtube.title.';
+  }
+  return null;
+}
+
+/** Resolve the exact upload title, including an explicit destination override. */
+export function projectYoutubeTitle({ title, caption, options } = {}) {
+  const source = options?.title?.trim() || title?.trim() || caption?.trim() || "";
+  const problem = internalTitleProblem(source);
+  return {
+    title: youtubeTitle(source),
+    problems: [
+      ...(source ? [] : ["YouTube Shorts requires a title or a caption to use as one"]),
+      ...(problem ? [problem] : []),
+    ],
+  };
+}
+
+export function projectPost(post) {
+  const igCaption = (post.captionInstagram ?? "").trim();
+  const ttCaption = (post.captionTiktok ?? "").trim() || igCaption;
+  const title = (post.title ?? "").trim();
+  const platforms = post.platforms ?? ["instagram", "tiktok", "youtube"];
+
+  const out = [];
+  for (const platform of platforms) {
+    if (platform === "instagram") {
+      out.push({
+        platform,
+        title: null, // Instagram has no title concept and ignores one.
+        body: igCaption,
+        problems: igCaption ? [] : ["no caption: the post publishes bare"],
+      });
+      continue;
+    }
+    if (platform === "tiktok") {
+      const shown = title ? title.slice(0, TIKTOK_TITLE_MAX) : ttCaption.slice(0, TIKTOK_TITLE_MAX);
+      out.push({
+        platform,
+        title: shown || null,
+        body: ttCaption,
+        problems: [
+          ...(ttCaption ? [] : ["no caption: the post publishes bare"]),
+          ...(title && looksLikeSlug(title) ? [`the in-app title is a slug: "${title}"`] : []),
+        ],
+      });
+      continue;
+    }
+    if (platform === "youtube") {
+      const projected = projectYoutubeTitle({ title, caption: igCaption, options: post.options?.youtube });
+      out.push({
+        platform,
+        title: projected.title,
+        body: igCaption,
+        problems: [
+          ...projected.problems,
+          ...(looksLikeSlug(projected.title) ? [`the Short's title is a slug: "${projected.title}"`] : []),
+          // A caption whose first line does not fit is cut, which is legal and
+          // reads worse. Say so where it can still be fixed.
+          ...(!post.options?.youtube?.title?.trim() && !title && igCaption && igCaption.split("\n")[0].trim().length > 100
+            ? ["the caption's first line is longer than a Short's title, so it is cut"]
+            : []),
+        ],
+      });
+      continue;
+    }
+    if (platform === "pinterest") {
+      const pin = post.options?.pinterest ?? post.pinterestOptions ?? {};
+      const link = typeof pin.link === "string" ? pin.link.trim() : "";
+      let validLink = false;
+      try {
+        const parsed = new URL(link);
+        validLink = parsed.protocol === "http:" || parsed.protocol === "https:";
+      } catch {}
+      out.push({
+        platform,
+        title: typeof pin.title === "string" && pin.title.trim() ? pin.title.trim() : null,
+        body: typeof pin.description === "string" ? pin.description.trim() : "",
+        problems: [
+          ...(pin.boardId ? [] : ["choose a Pinterest board"]),
+          ...(validLink ? [] : ["add an absolute http or https destination link"]),
+          ...((pin.title?.length ?? 0) <= 100 ? [] : ["Pinterest title exceeds 100 characters"]),
+          ...((pin.description?.length ?? 0) <= 800 ? [] : ["Pinterest description exceeds 800 characters"]),
+          ...((pin.altText?.length ?? 0) <= 500 ? [] : ["Pinterest alt text exceeds 500 characters"]),
+        ],
+      });
+      continue;
+    }
+    // Everything else publishes the caption and nothing else we model yet.
+    out.push({ platform, title: title || null, body: igCaption, problems: [] });
+  }
+  return out;
+}
+
+// ─── the YouTube title, moved here from the adapter ────────────────────────
+
+/** YouTube rejects a snippet.title over 100 UTF-16 chars with a 400. */
+const YT_TITLE_MAX = 100;
+const SHORTS_TAG = " #Shorts";
+
+/**
+ * The title YouTube will accept.
+ *
+ * The optional #Shorts tag is budgeted before truncation. Without it, the
+ * entire character allowance is available to the title.
+ */
+export function youtubeTitle(raw, { shortsTag = false } = {}) {
+  const trimmed = raw.trim();
+  if (trimmed.includes("#Shorts")) return trimmed.slice(0, YT_TITLE_MAX);
+  const room = shortsTag ? YT_TITLE_MAX - SHORTS_TAG.length : YT_TITLE_MAX;
+  const tag = shortsTag ? SHORTS_TAG : "";
+
+  // Prefer a complete first line when it fits the title budget.
+  const firstLine = trimmed.split("\n")[0].trim();
+  if (firstLine && firstLine.length <= room) return `${firstLine}${tag}`;
+
+  // Still too long, so it has to be cut - but cut at a word. A title ending
+  // "...for" reads as broken; one ending "...the example" reads as a title.
+  const cut = trimmed.slice(0, room);
+  const lastSpace = cut.lastIndexOf(" ");
+  const body = lastSpace > room * 0.6 ? cut.slice(0, lastSpace) : cut;
+  return `${body.trimEnd().replace(/[,;:\-]$/, "")}${tag}`;
+}