@sprid/cli 0.1.2

package/src/post/screen/captions.mjs

@@ -0,0 +1,131 @@
+// TikTok-style captions: two or three words at a time, on the rhythm of
+// someone saying them.
+//
+// **Why not one long line held for four seconds.** A screen recording is
+// already asking the eye to track a moving UI; a static paragraph over it gets
+// read once, in the first 400ms, and then competes with the thing it is meant
+// to explain. Chunks that change on the beat are read continuously and cost the
+// UI nothing, which is why every account that does this well does it this way.
+//
+// The timing model is Sprid's own `reels/prosody.ts`, restated small and with
+// no dependency: **weights, not milliseconds.** A word's share of its window
+// tracks its syllables, and the pauses that carry a sentence's shape sit at its
+// punctuation. Even spacing is what makes a word-by-word fill read as a machine
+// effect - "you" and "apologised" get the same beat and a full stop passes
+// without anyone drawing breath.
+
+const SYLLABLE = 1;
+const ONSET = 0.34;
+const COMMA = 2.6;   // a breath
+const STOP = 5.6;    // the sentence lands
+const DASH = 3.8;
+
+/** Roughly the word rate of a caption read aloud. Sprid's own figure. */
+export const MS_PER_WORD = 330;
+
+/**
+ * Syllables, estimated.
+ *
+ * The `syllable` package is a dictionary and this package has no dependencies,
+ * so this counts vowel groups - within about 8% on English and better than that
+ * on the Germanic locales, which is well inside what a 330ms beat can show.
+ * Japanese counts mora instead, because a kana IS the beat.
+ */
+export function syllables(word, locale = "en") {
+  if (locale.startsWith("ja")) {
+    const kana = word.replace(/[^぀-ヿ一-鿿]/g, "");
+    // Small kana attach to the mora before them; a kanji averages two.
+    const small = (kana.match(/[ぁぃぅぇぉゃゅょっァィゥェォャュョッ]/g) ?? []).length;
+    const kanji = (kana.match(/[一-鿿]/g) ?? []).length;
+    return Math.max(1, kana.length - small + kanji);
+  }
+  const w = word.toLowerCase().replace(/[^a-zà-öø-ÿ']/g, "");
+  if (!w) return 1;
+  const groups = w.match(/[aeiouyà-öø-ÿ]+/g) ?? [];
+  let n = groups.length;
+  if (/[^aeiou]e$/.test(w) && n > 1) n -= 1;   // silent final e
+  return Math.max(1, n);
+}
+
+function weightOf(word, locale) {
+  let w = ONSET + SYLLABLE * syllables(word, locale);
+  if (/[.!?]["”')]?$/.test(word)) w += STOP;
+  else if (/[,;:]["”')]?$/.test(word)) w += COMMA;
+  else if (/(-|–|…|\.\.\.)$/.test(word)) w += DASH;
+  return w;
+}
+
+/**
+ * Group a line into cards of at most `maxWords` words and `maxChars`
+ * characters, never carrying a clause boundary into the middle of a card.
+ *
+ * The break-after-punctuation rule is the one that matters: a card reading
+ * "yes. Then" makes the reader do the sentence boundary twice.
+ */
+export function chunk(text, { maxWords = 3, maxChars = 22 } = {}) {
+  const words = text.trim().split(/\s+/).filter(Boolean);
+  const out = [];
+  let cur = [];
+  const flush = () => { if (cur.length) { out.push(cur); cur = []; } };
+  for (const w of words) {
+    const wouldBe = [...cur, w];
+    if (cur.length && (wouldBe.length > maxWords || wouldBe.join(" ").length > maxChars)) flush();
+    cur.push(w);
+    if (/[.!?,;:]["”')]?$/.test(w)) flush();
+  }
+  flush();
+  return out.map((c) => c.join(" "));
+}
+
+/**
+ * Lay the cards of one caption out across the window between its mark and the
+ * next one.
+ *
+ * **A window that is longer than the words need is left empty at the end, not
+ * stretched.** Stretching is the tempting version and it is wrong twice: it
+ * makes every card in a slow passage crawl, and it removes the only moment in
+ * the reel where the viewer is looking at the app with nothing written over it.
+ * That moment is the product demo.
+ */
+export function layout(entries, marks, endMs, { locale = "en", msPerWord = MS_PER_WORD, minHoldMs = 520, maxHoldMs = 1500 } = {}) {
+  const anchored = entries.map((e) => {
+    const at = typeof e.at === "number" ? e.at : marks[e.at];
+    if (at == null) throw new Error(`Caption anchored to "${e.at}", which the script never marks.`);
+    return { ...e, at: at + (e.after ?? 0) };
+  }).sort((a, b) => a.at - b.at);
+
+  const cards = [];
+  const warnings = [];
+  anchored.forEach((e, i) => {
+    const winStart = e.at;
+    const winEnd = Math.min(e.until != null ? (typeof e.until === "number" ? e.until : marks[e.until]) : Infinity,
+                            i + 1 < anchored.length ? anchored[i + 1].at : endMs, endMs);
+    const window = winEnd - winStart;
+    if (window <= 0) { warnings.push(`"${e.text.slice(0, 30)}…" has no room before the next caption.`); return; }
+
+    const texts = chunk(e.text, e.chunk ?? {});
+    const weights = texts.map((t) => t.split(/\s+/).reduce((s, w) => s + weightOf(w, locale), 0));
+    const totalWeight = weights.reduce((a, b) => a + b, 0);
+    const words = e.text.trim().split(/\s+/).length;
+    const needed = words * msPerWord;
+    const span = Math.min(window, Math.max(needed, texts.length * 420));
+    if (needed > window + 1)
+      warnings.push(`"${e.text.slice(0, 34)}…" needs ${(needed / 1000).toFixed(1)}s but its beat is ${(window / 1000).toFixed(1)}s - cut words, or move the mark.`);
+
+    // Prosody sets the SHAPE; the floor and the ceiling keep it readable. A
+    // three-word card at 550ms is gone before the eye has finished the second
+    // word, and prosody produces exactly that whenever a short card sits next
+    // to one carrying a full stop. Clamp, then rescale what is left so the
+    // beat still ends where it should.
+    let held = weights.map((w) => Math.min(maxHoldMs, Math.max(minHoldMs, (w / totalWeight) * span)));
+    const over = held.reduce((a, b) => a + b, 0);
+    if (over > window) held = held.map((d) => (d / over) * window);
+
+    let t = winStart;
+    texts.forEach((text, j) => {
+      cards.push({ text, start: t, end: Math.min(t + held[j], winEnd), line: e.line ?? null, style: e.style ?? null });
+      t += held[j];
+    });
+  });
+  return { cards, warnings };
+}

package/src/post/screen/compose.mjs

@@ -0,0 +1,284 @@
+// The screen recording becomes a reel.
+//
+// Everything here is one ffmpeg graph plus, when there is b-roll, a concat of
+// two files encoded to identical parameters. The order is deliberate:
+//
+//   VFR -> 30fps      before anything measures time
+//   trim              from the clapper, so the timeline's zero is the video's
+//   blurred bed       the app is 9:19.6 and a reel is 9:16
+//   handheld drift    a locked-off frame is the tell that nothing was filmed
+//   touch dots        a screen recording has no finger in it
+//   captions          two or three words on the beat
+//   music             measured on the EXCERPT, limited at -3 dBFS
+//
+// Nothing in it is clever. The two places that cost a rebuild if you get them
+// wrong are marked.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const W = 1080, H = 1920, FPS = 30;
+
+const run = (args, opts = {}) => spawnSync("ffmpeg", ["-hide_banner", "-nostats", ...args], { encoding: "utf8", ...opts });
+
+/** ffmpeg expressions read better with the numbers already rounded. */
+const n = (v, d = 3) => Number(v).toFixed(d).replace(/\.?0+$/, "") || "0";
+
+// ---------------------------------------------------------------------------
+// the clapperboard, found
+// ---------------------------------------------------------------------------
+
+/**
+ * Where in the video the UI went dark.
+ *
+ * `recordVideo` reports nothing about when it opened the stream, and the gap
+ * between spawn and first frame is neither constant nor small. So the run
+ * flashes the whole UI and this finds the flash: sample the luma of a 32-pixel
+ * thumbnail ten times a second and take the first sustained drop.
+ */
+export function findClappers(video, { dropRatio = 0.55 } = {}) {
+  const r = run(["-i", video,
+    "-vf", "fps=10,scale=48:-1,signalstats,metadata=print:key=lavfi.signalstats.YAVG:file=-",
+    "-f", "null", "-"]);
+  const out = (r.stdout || "") + (r.stderr || "");
+  const samples = [];
+  const re = /pts_time:([\d.]+)[\s\S]*?lavfi\.signalstats\.YAVG=([\d.]+)/g;
+  let m;
+  while ((m = re.exec(out))) samples.push({ t: Number(m[1]), y: Number(m[2]) });
+  if (samples.length < 20) return [];
+
+  // The bar is set from the BRIGHT half of the run, not from the opening
+  // frames: the opening frames are the springboard on its way to dark.
+  const sorted = [...samples].map((s) => s.y).sort((a, b) => a - b);
+  const bright = sorted[Math.floor(sorted.length * 0.75)];
+
+  const plateaus = [];
+  let start = null;
+  for (const s of samples) {
+    if (s.y < bright * dropRatio) { if (start == null) start = s.t; }
+    else if (start != null) { if (s.t - start >= 0.3) plateaus.push({ start, end: s.t }); start = null; }
+  }
+  return plateaus;
+}
+
+/**
+ * **The recorder's clock is not the wall clock, so the run measures it.**
+ *
+ * A single anchor was the first design and it drifts: events at the end of a
+ * 75-second recording landed 4.5s from where the wall clock said they were,
+ * which is a RATE error, not an offset - one flash cannot see it and one flash
+ * is what the first version had. Two flashes, one before the app comes up and
+ * one after the script finishes, give both numbers:
+ *
+ *   videoSeconds(wallMs) = v0 + k * wallMs / 1000
+ *
+ * `k` came out around 0.97 here, so a caption bound to the last mark of a long
+ * script was two seconds late on the screen it describes. Nothing about that is
+ * visible until you watch it, which is the argument for measuring rather than
+ * assuming.
+ */
+export function solveClock(plateaus, wallStartMs, wallEndMs) {
+  if (plateaus.length < 2) return null;
+  const first = plateaus[0].start, last = plateaus[plateaus.length - 1].start;
+  const k = (last - first) / ((wallEndMs - wallStartMs) / 1000);
+  return { v0: first - k * wallStartMs / 1000, k, first, last };
+}
+
+// ---------------------------------------------------------------------------
+// the caption cards
+// ---------------------------------------------------------------------------
+
+export function renderCaptions(cards, { simkitBin, dir, fontFile, size = 82, width = 940, stroke = 5, pill = 0, color = "ffffff" }) {
+  mkdirSync(dir, { recursive: true });
+  return cards.map((c, i) => {
+    const out = join(dir, `cap-${String(i).padStart(3, "0")}.png`);
+    const args = ["text", "--out", out, "--w", String(width), "--size", String(size),
+      "--stroke", String(stroke), "--color", color, ...(pill ? ["--pill", String(pill)] : [])];
+    if (fontFile) args.push("--font-file", fontFile);
+    for (const line of wrap(c.text)) args.push("--line", line);
+    const r = spawnSync(simkitBin, args, { encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`caption render failed: ${r.stderr}`);
+    const [w, h] = r.stdout.trim().split(/\s+/).map(Number);
+    return { ...c, png: out, w, h };
+  });
+}
+
+/** Two or three words never need more than two lines; this only saves the case
+ *  where one of them is very long. */
+function wrap(text, max = 22) {
+  const words = text.split(/\s+/);
+  const lines = [];
+  let cur = "";
+  for (const w of words) {
+    if (cur && (cur + " " + w).length > max) { lines.push(cur); cur = w; }
+    else cur = cur ? cur + " " + w : w;
+  }
+  if (cur) lines.push(cur);
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// the graph
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional handheld drift, **off by default**.
+ *
+ * Two sine pairs at incommensurable periods and no rotation - rotation costs a
+ * full resample per frame and reads as a wobble rather than a hand. The same
+ * expression drives the touch dots, or the finger detaches from the screen it
+ * is supposed to be touching.
+ *
+ * At amp 0 both expressions collapse to `0` and the frame is locked, which is
+ * the default and what a screen recording should be: the status bar is
+ * pin-sharp, so drifting the phone reads as an unstable video rather than as
+ * one that was filmed.
+ */
+function driftExpr(amp) {
+  const a = amp;
+  if (!a) return { x: "0", y: "0" };
+  return {
+    x: `(${n(a * 1.0)}*sin(2*PI*t/7.3)+${n(a * 0.6)}*sin(2*PI*t/4.1+1.1))`,
+    y: `(${n(a * 0.8)}*sin(2*PI*t/5.9+0.4)+${n(a * 0.5)}*sin(2*PI*t/3.3))`,
+  };
+}
+
+/**
+ * The finger.
+ *
+ * A tap is a dot that appears where the finger lands; a swipe is a dot that
+ * travels the same eased path simkit posted, so what the viewer sees moving and
+ * what the list is responding to are the same gesture. `pow(p,1.55)` is
+ * simkit's own flick curve - if the two ever disagree the dot arrives after the
+ * content it is supposed to be dragging.
+ */
+function dotExprs(gestures, geom, drift, videoOffsetMs, dotSize) {
+  const { fx, fy, fw, fh } = geom;
+  const enable = [], xs = [], ys = [];
+  for (const g of gestures) {
+    const t0 = (g.t - videoOffsetMs) / 1000;
+    const t1 = t0 + g.durationMs / 1000;
+    if (t1 < 0) continue;
+    enable.push(`between(t,${n(Math.max(0, t0))},${n(t1)})`);
+    const [a, b] = g.points.length > 1 ? g.points : [g.points[0], g.points[0]];
+    const px = (p) => n(fx + p[0] * fw - dotSize / 2, 1);
+    const py = (p) => n(fy + p[1] * fh - dotSize / 2, 1);
+    if (g.kind === "tap") {
+      xs.push([`between(t,${n(Math.max(0, t0))},${n(t1)})`, px(a)]);
+      ys.push([`between(t,${n(Math.max(0, t0))},${n(t1)})`, py(a)]);
+    } else {
+      const p = `pow(clip((t-${n(t0)})/${n(g.durationMs / 1000 - 0.26)},0,1),1.55)`;
+      xs.push([`between(t,${n(Math.max(0, t0))},${n(t1)})`, `(${px(a)}+(${px(b)}-${px(a)})*${p})`]);
+      ys.push([`between(t,${n(Math.max(0, t0))},${n(t1)})`, `(${py(a)}+(${py(b)}-${py(a)})*${p})`]);
+    }
+  }
+  if (!enable.length) return null;
+  const chain = (pairs, fallback) => pairs.reduceRight((acc, [cond, val]) => `if(${cond},${val},${acc})`, fallback);
+  return {
+    enable: enable.join("+"),
+    x: `${chain(xs, "0")}+${drift.x}`,
+    y: `${chain(ys, "0")}+${drift.y}`,
+  };
+}
+
+export function buildGraph({ cards, gestures, geom, drift, videoOffsetMs, dotSize, capY, background, trimStart, duration, speed = 1 }) {
+  const parts = [];
+  const { fx, fy, fw, fh } = geom;
+
+  // **`fps` first, and on the source.** A `simctl` recording is variable frame
+  // rate; every `between(t,…)` below is in seconds, and a graph that resamples
+  // after the overlays drifts against them by whole seconds over 20s.
+  parts.push(`[0:v]fps=${FPS},trim=start=${n(trimStart, 4)}:duration=${n(duration, 4)},` +
+    `setpts=(PTS-STARTPTS)${speed === 1 ? "" : `/${n(speed)}`},split=2[src][bgsrc]`);
+
+  if (background !== "blur" && !/^(?:#[0-9a-f]{3,8}|0x[0-9a-f]{6,8}|[a-z][a-z0-9-]*)$/i.test(background)) {
+    throw new Error("render.background must be 'blur', a color name, or a hex color.");
+  }
+  if (background === "blur") {
+    // The bed. Scaled past the frame, blurred, and darkened, so the eye reads
+    // the phone as the subject rather than a picture pasted on a colour.
+    parts.push(`[bgsrc]scale=${W * 1.4}:-2,crop=${W}:${H},gblur=sigma=42,eq=brightness=-0.07:saturation=0.85,setsar=1[bg]`);
+  } else {
+    parts.push(`[bgsrc]drawbox=x=0:y=0:w=iw:h=ih:color=${background}:t=fill,scale=${W}:${H},setsar=1[bg]`);
+  }
+
+  parts.push(`[src]scale=${Math.round(fw)}:${Math.round(fh)}:flags=lanczos,setsar=1[fg]`);
+  parts.push(`[bg][fg]overlay=x='${n(fx, 1)}+${drift.x}':y='${n(fy, 1)}+${drift.y}'[v0]`);
+
+  let last = "v0";
+  let input = 1;
+
+  const dots = dotExprs(gestures, geom, drift, videoOffsetMs, dotSize);
+  if (dots) {
+    parts.push(`[${input}:v][${last}]scale2ref=w=iw:h=ih[dotref][keep]`); // no-op guard, replaced below
+    parts.pop();
+    parts.push(`[${last}][${input}:v]overlay=x='${dots.x}':y='${dots.y}':enable='${dots.enable}'[v${input}]`);
+    last = `v${input}`;
+    input += 1;
+  }
+
+  for (const c of cards) {
+    const t0 = (c.start - videoOffsetMs) / 1000;
+    const t1 = (c.end - videoOffsetMs) / 1000;
+    if (t1 <= 0) { input += 1; continue; }
+    // The pop: 14 pixels of rise over the first 90ms. A scale-up would be
+    // truer to the platform and costs a second scaled copy of every card.
+    const rise = `14*max(0,1-(t-${n(t0)})/0.09)`;
+    parts.push(`[${last}][${input}:v]overlay=x='(W-w)/2+${drift.x}':y='${n(capY - c.h, 1)}+${rise}+${drift.y}':enable='between(t,${n(Math.max(0, t0))},${n(t1)})'[v${input}]`);
+    last = `v${input}`;
+    input += 1;
+  }
+
+  parts.push(`[${last}]format=yuv420p[vout]`);
+  return parts.join(";");
+}
+
+// ---------------------------------------------------------------------------
+// audio
+// ---------------------------------------------------------------------------
+
+/**
+ * **Measure the excerpt, not the file.** A bed's integrated loudness is not its
+ * opening fifteen seconds', and getting this backwards is what put one of the
+ * pipelines this recipe was drawn from at 3.8 LUFS of spread across a batch -
+ * audible between two posts in a row.
+ */
+export function measureLufs(path, seconds) {
+  const r = run(["-t", seconds.toFixed(3), "-i", path, "-filter:a", "loudnorm=print_format=json", "-f", "null", "-"]);
+  const m = /"input_i"\s*:\s*"(-?[\d.]+)"/.exec(r.stderr ?? "");
+  if (!m) throw new Error(`Could not measure loudness of ${path}.`);
+  return Number(m[1]);
+}
+
+export function audioChain(inputIndex, track, seconds, { targetLufs = -14, fadeOut = 1.2 } = {}) {
+  const gain = targetLufs - measureLufs(track, seconds);
+  return `[${inputIndex}:a]atrim=start=0:end=${seconds.toFixed(3)},asetpts=PTS-STARTPTS,` +
+    `volume=${gain.toFixed(2)}dB,` +
+    // -3 dBFS, not -1.5: the AAC encode overshoots the limiter and a -1.5
+    // ceiling came back out of the mp4 at 0.0 with clipped samples.
+    `alimiter=limit=0.708:level=disabled,` +
+    `afade=t=in:st=0:d=0.4,afade=t=out:st=${Math.max(0, seconds - fadeOut).toFixed(3)}:d=${fadeOut}[aout]`;
+}
+
+// ---------------------------------------------------------------------------
+// b-roll
+// ---------------------------------------------------------------------------
+
+/**
+ * The opener, cut hard into the screen recording.
+ *
+ * **A cut, never a dissolve.** A dissolve tells the viewer a scene is ending,
+ * which at second two is an invitation to leave; a cut on the same beat reads
+ * as the same person still talking.
+ */
+export function encodeBroll(clip, { out, seconds, ss = 0, crf = 20 }) {
+  mkdirSync(dirname(out), { recursive: true });
+  const r = run(["-y", "-ss", String(ss), "-t", String(seconds), "-i", clip,
+    "-vf", `fps=${FPS},scale=${W}:${H}:force_original_aspect_ratio=increase,crop=${W}:${H},setsar=1,format=yuv420p`,
+    "-an", "-c:v", "libx264", "-crf", String(crf), "-preset", "medium", "-pix_fmt", "yuv420p", out]);
+  if (r.status !== 0) throw new Error(`b-roll encode failed:\n${r.stderr.slice(-1500)}`);
+  return out;
+}
+
+export { W, H, FPS, run, driftExpr };

package/src/post/screen/input.mjs

@@ -0,0 +1,163 @@
+// The finger.
+//
+// **Two backends, and the good one does not touch the machine.**
+//
+// `baguette` (Homebrew, Apple Silicon, Xcode 26) injects touches through
+// SimulatorKit's private symbols with the iOS-26 calling conventions. Nothing
+// is focused, the pointer never moves, and the Simulator does not come to the
+// front - so a run costs the machine nothing and you can keep working through
+// it. `baguette input` reads newline-delimited JSON gestures from stdin, which
+// is the part that matters: **we keep our own velocity curve.** A canned
+// `swipe --duration` would be a linear interpolation, and a linear
+// interpolation is the single thing that makes a scripted scroll read as
+// scripted.
+//
+// The CGEvent backend below is the fallback, and it is a real fallback rather
+// than a preference: posting to the global HID tap is the ONLY way to reach the
+// Simulator without baguette, and the global tap owns the pointer for the
+// length of the run. Measured 2026-09-06: `CGEventPostToPid`, plain and with
+// fields 91/92 set to the Simulator's window number, delivers without moving
+// the cursor and is ignored. Do not spend another hour on it.
+//
+// Coordinates are normalised 0..1 in both backends. baguette scales x/y by the
+// width/height you pass, so the device's pixel size goes straight in and there
+// is no window geometry to calibrate at all - which also means resizing the
+// Simulator window cannot break a run.
+
+import { spawn, spawnSync } from "node:child_process";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// --- the curves -------------------------------------------------------------
+// These are the canonical ones. `simkit.swift` mirrors them for the CGEvent
+// backend; if you change one, change both.
+
+/** A deliberate drag that arrives and stops - for reading, not for browsing. */
+const easeInOut = (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2);
+/**
+ * **A flick still moving at the moment of release.** iOS reads the last few
+ * milliseconds of travel as the throw velocity, so a curve that decelerates
+ * into its endpoint hands it zero and the list stops dead under the finger.
+ */
+const easeInHold = (t) => Math.pow(t, 1.55);
+
+const rand = (a, b) => a + Math.random() * (b - a);
+const jit = (a) => (a <= 0 ? 0 : rand(-a, a));
+
+/** 120Hz asked for; baguette streams ~110Hz through a pipe, which is plenty. */
+const HZ = 120;
+
+export function hasBaguette() {
+  return spawnSync("baguette", ["--version"], { encoding: "utf8" }).status === 0;
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.udid
+ * @param {{w:number,h:number}} o.px  the device screen in pixels
+ * @param {(args:string[])=>string} o.kit  simkit, for the CGEvent fallback
+ * @param {{x,y,w,h}} [o.rect] the Simulator window's device rect, CGEvent only
+ * @param {"baguette"|"cgevent"} [o.backend]
+ */
+export function openInput({ udid, px, kit, rect, backend, log = () => {} }) {
+  const chosen = backend ?? (hasBaguette() ? "baguette" : "cgevent");
+  if (chosen === "cgevent") {
+    log("  input   CGEvent - this takes over the pointer and brings the Simulator forward.\n" +
+        "          `brew install baguette` and it runs in the background instead.");
+    return cgEventInput(kit, rect);
+  }
+  log("  input   baguette - background, the pointer stays yours");
+  return baguetteInput(udid, px);
+}
+
+// --- baguette ---------------------------------------------------------------
+
+function baguetteInput(udid, px) {
+  const proc = spawn("baguette", ["input", "--udid", udid], { stdio: ["pipe", "pipe", "pipe"] });
+  let failed = null;
+  proc.stdout.on("data", (d) => {
+    for (const line of String(d).split("\n").filter(Boolean)) {
+      try { const r = JSON.parse(line); if (r.ok === false) failed = r.error; } catch { /* a log line */ }
+    }
+  });
+  proc.stderr.on("data", () => {});
+
+  // **Paced by the clock, not by the acknowledgements.** Awaiting each ack
+  // would make the sample rate a function of pipe latency, and the whole point
+  // of streaming rather than calling `baguette swipe` is that WE own the
+  // timing. Errors are read off stdout in the background and raised at the end
+  // of the gesture instead.
+  const send = (type, nx, ny) => {
+    proc.stdin.write(JSON.stringify({
+      type, x: Math.round(nx * px.w), y: Math.round(ny * px.h), width: px.w, height: px.h,
+    }) + "\n");
+  };
+  const check = () => { if (failed) throw new Error(`baguette rejected a gesture: ${failed}`); };
+
+  return {
+    backend: "baguette",
+    /**
+     * **A tap goes through baguette's one-shot path, not the stream.**
+     *
+     * The streaming `touch1-*` path is `IOHIDDigitizerDispatch`, built for
+     * continuous gestures - swipes, edge pulls, app-switcher drags - and it is
+     * the reason we can keep our own velocity curve. It is not equally good at
+     * a discrete tap: UIKit tab bars can ignore streamed taps that React Native
+     * views accept. Use the dedicated tap command for discrete input.
+     *
+     * A tap has no timing worth owning anyway, which is what makes this a free
+     * trade: one process spawn, about 100ms.
+     */
+    async tap(nx, ny, { holdMs = rand(55, 100) } = {}) {
+      const r = spawnSync("baguette", ["tap", "--udid", udid,
+        "--x", String(Math.round(nx * px.w)), "--y", String(Math.round(ny * px.h)),
+        "--width", String(px.w), "--height", String(px.h),
+        "--duration", (holdMs / 1000).toFixed(3)], { encoding: "utf8" });
+      if (r.status !== 0) throw new Error(`baguette tap failed: ${r.stderr}`);
+      await sleep(40);
+    },
+    async swipe(x1, y1, x2, y2, { durationMs = 280, flick = true, bow = 0.025, settleMs = 90 } = {}) {
+      const dx = x2 - x1, dy = y2 - y1;
+      const dist = Math.hypot(dx, dy);
+      // A perpendicular bow: nobody drags a straight line.
+      const nx = dist > 0 ? -dy / dist : 0, ny = dist > 0 ? dx / dist : 0;
+      const bowAmt = bow * dist * (Math.random() < 0.5 ? 1 : -1);
+
+      const steps = Math.max(4, Math.round(durationMs / (1000 / HZ)));
+      const t0 = Date.now();
+      send("touch1-down", x1, y1);
+      await sleep(rand(12, 28));                 // press, then travel
+      for (let i = 1; i <= steps; i++) {
+        const e = flick ? easeInHold(i / steps) : easeInOut(i / steps);
+        const arc = Math.sin(e * Math.PI) * bowAmt;
+        send("touch1-move", x1 + dx * e + nx * arc + jit(0.0008), y1 + dy * e + ny * arc + jit(0.0008));
+        const wait = t0 + 20 + (i * durationMs) / steps - Date.now();
+        if (wait > 0) await sleep(wait);
+      }
+      if (!flick) await sleep(settleMs);          // a precise drag stops, then lifts
+      send("touch1-up", x2, y2);
+      await sleep(40);
+      check();
+    },
+    close() { try { proc.stdin.end(); } catch { /* already gone */ } },
+  };
+}
+
+// --- CGEvent ----------------------------------------------------------------
+
+function cgEventInput(kit, rect) {
+  const rectArg = ["--rect", `${rect.x},${rect.y},${rect.w},${rect.h}`];
+  return {
+    backend: "cgevent",
+    async tap(nx, ny, { holdMs } = {}) {
+      kit(["tap", "--x", String(nx), "--y", String(ny), ...rectArg,
+        ...(holdMs ? ["--hold", String(holdMs)] : [])]);
+    },
+    async swipe(x1, y1, x2, y2, { durationMs = 280, flick = true, bow } = {}) {
+      kit(["swipe", "--x1", String(x1), "--y1", String(y1), "--x2", String(x2), "--y2", String(y2),
+        "--duration", String(durationMs), ...(flick ? [] : ["--precise"]),
+        ...(bow != null ? ["--bow", String(bow)] : []), ...rectArg]);
+    },
+    close() {},
+  };
+}