@olegkoval/agent-skills 1.60.0 → 1.62.0

package/plugins/olko-creative/skills/shorts-animator/scripts/domain/check.ts

@@ -0,0 +1,96 @@
+// `SA check`: catch the defects a render would show, before paying for one. Each rule is a pure
+// function over plain facts; the edge gathers the facts (scene probes, kit and look vocabularies).
+import { words } from "./captions.ts";
+import { isMap } from "./schema.ts";
+import type { JsonMap, Short, Timeline } from "./types.ts";
+
+export type Call = { readonly fn: string; readonly opts: JsonMap };
+export type Probe = { readonly scene: string; readonly calls: readonly Call[]; readonly error?: string };
+export type Facts = {
+  readonly short: Short;
+  readonly timeline: Timeline;
+  readonly probes: readonly Probe[];
+  readonly kit: readonly string[];
+  readonly lookKeys: readonly string[];
+};
+export type Finding = { readonly level: "error" | "warn"; readonly where: string; readonly msg: string };
+
+export const MOVES = ["push", "pull", "pan-left", "pan-right", "rise", "fall", "drift", "still"];
+export const TRANSITIONS = ["cut", "fade", "dip"];
+const LOOK_META = ["base", "palette", "captions", "about"];
+const WORDS = { min: 4, max: 12 };
+const SECONDS = { min: 20, max: 45 };
+const BAND = 0.04;
+
+const err = (where: string, msg: string): Finding => ({ level: "error", where, msg });
+const warn = (where: string, msg: string): Finding => ({ level: "warn", where, msg });
+const num = (o: JsonMap, k: string, d: number): number => {
+  const v = o[k];
+  return typeof v === "number" ? v : d;
+};
+
+const unknownScenes = ({ timeline, probes }: Facts): readonly Finding[] => {
+  const known = new Set(probes.map((p) => p.scene));
+  return timeline.beats
+    .filter((b) => !known.has(b.scene))
+    .map((b) => err(`lines[${b.line}]`, `no scene "${b.scene}" in scenes.js (renders as a red frame)`));
+};
+
+const unknownMoves = ({ timeline }: Facts): readonly Finding[] =>
+  timeline.beats.flatMap((b) => [
+    ...(MOVES.includes(b.move) ? [] : [warn(`lines[${b.line}]`, `move "${b.move}" is not one of ${MOVES.join(", ")}; it renders as still`)]),
+    ...(TRANSITIONS.includes(b.transition) ? [] : [warn(`lines[${b.line}]`, `transition "${b.transition}" is not one of ${TRANSITIONS.join(", ")}; it renders as a cut`)]),
+  ]);
+
+const unknownLookKeys = ({ short, lookKeys }: Facts): readonly Finding[] => {
+  if (!isMap(short.look)) return [];
+  const known = new Set([...lookKeys, ...LOOK_META]);
+  return Object.keys(short.look)
+    .filter((k) => !known.has(k))
+    .map((k) => warn("look", `"${k}" is not a look setting; it is ignored`));
+};
+
+const lineLengths = ({ short }: Facts): readonly Finding[] =>
+  short.lines.flatMap((l, i) => {
+    const n = words(l.say).length;
+    return n < WORDS.min || n > WORDS.max ? [warn(`lines[${i}]`, `${n} words; lines of ${WORDS.min} to ${WORDS.max} read best`)] : [];
+  });
+
+const totalLength = ({ timeline: { duration } }: Facts): readonly Finding[] =>
+  duration < SECONDS.min || duration > SECONDS.max
+    ? [warn("short", `${duration.toFixed(1)}s long; ${SECONDS.min} to ${SECONDS.max}s holds attention best`)]
+    : [];
+
+const sceneErrors = ({ probes }: Facts): readonly Finding[] =>
+  probes.flatMap((p) => (p.error === undefined ? [] : [err(`scene "${p.scene}"`, `throws: ${p.error}`)]));
+
+const unknownKit = ({ probes, kit }: Facts): readonly Finding[] => {
+  const known = new Set(kit);
+  return probes.flatMap((p) =>
+    [...new Set(p.calls.map((c) => c.fn))].filter((fn) => !known.has(fn)).map((fn) => err(`scene "${p.scene}"`, `k.${fn} is not in the kit`)),
+  );
+};
+
+/** A figure whose body spans the caption line gets text drawn across it. */
+const crossesBand = (c: Call, y: number): boolean => {
+  if (c.fn !== "person") return false;
+  const feet = num(c.opts, "y", 0.85);
+  const head = feet - num(c.opts, "h", 0.3) * num(c.opts, "scale", 1);
+  return head < y + BAND && feet > y - BAND;
+};
+
+const captionOverlap = ({ short, timeline, probes }: Facts): readonly Finding[] => {
+  if (short.captions.style === "none" || timeline.track.length === 0) return [];
+  const y = num(short.captions, "y", 0.775);
+  const used = new Set(timeline.beats.map((b) => b.scene));
+  return probes
+    .filter((p) => used.has(p.scene) && p.calls.some((c) => crossesBand(c, y)))
+    .map((p) => warn(`scene "${p.scene}"`, `a person crosses the caption line at y=${y}; raise them, shrink them, or set captions.y`));
+};
+
+const RULES = [sceneErrors, unknownScenes, unknownKit, unknownMoves, unknownLookKeys, captionOverlap, lineLengths, totalLength];
+
+export const check = (facts: Facts): readonly Finding[] => RULES.flatMap((rule) => rule(facts));
+
+export const report = (fs: readonly Finding[]): string =>
+  fs.length === 0 ? "check: clean" : fs.map((f) => `${f.level === "error" ? "ERROR" : "warn "} ${f.where}: ${f.msg}`).join("\n");

package/plugins/olko-creative/skills/shorts-animator/scripts/domain/look.ts

@@ -0,0 +1,26 @@
+import { isMap } from "./schema.ts";
+import type { Json, JsonMap, Result, Short, Timeline } from "./types.ts";
+import { fail, ok } from "./types.ts";
+
+export type Named = (name: string) => Result<JsonMap>;
+
+const sub = (o: JsonMap, k: string): JsonMap => {
+  const v = o[k];
+  return isMap(v) ? v : {};
+};
+
+/** A look is a name from looks/, or an object with an optional `base` name plus overrides. */
+export function resolveLook(spec: Json, named: Named): Result<JsonMap> {
+  if (typeof spec === "string") return named(spec || "oil");
+  if (!isMap(spec)) return spec === null ? named("oil") : fail("look must be a name or an object");
+  const base = typeof spec.base === "string" ? named(spec.base) : ok<JsonMap>({});
+  if (!base.ok) return base;
+  return ok({ ...base.value, ...spec, palette: { ...sub(base.value, "palette"), ...sub(spec, "palette") } });
+}
+
+/** What the page reads as window.SHORT: the timeline, the look with the short's palette over it, the captions. */
+export const pageState = (s: Short, tl: Timeline, look: JsonMap) => ({
+  ...tl,
+  look: { ...look, ...(s.palette ? { palette: { ...sub(look, "palette"), ...s.palette } } : {}) },
+  captions: { ...sub(look, "captions"), ...s.captions },
+});

package/plugins/olko-creative/skills/shorts-animator/scripts/domain/patch.ts

@@ -0,0 +1,38 @@
+// `SA set dir key.path=value`: an immutable path update over plain JSON.
+import { isJson, isMap } from "./schema.ts";
+import type { Json, Result } from "./types.ts";
+import { fail, ok } from "./types.ts";
+
+export type Assignment = { readonly path: readonly string[]; readonly value: Json };
+
+const parseValue = (raw: string): Json => {
+  try {
+    const v: unknown = JSON.parse(raw);
+    return isJson(v) ? v : raw;
+  } catch {
+    return raw;
+  }
+};
+
+/** "lines.0.say=Hello" becomes a path and a value; values are JSON when they parse, text otherwise. */
+export function parseAssignment(arg: string): Result<Assignment> {
+  const i = arg.indexOf("=");
+  if (i <= 0) return fail(`"${arg}" is not key=value (e.g. look=watercolor, lines.0.hold=0.8)`);
+  const path = arg.slice(0, i).split(".");
+  if (path.some((k) => k === "")) return fail(`"${arg.slice(0, i)}" has an empty key`);
+  return ok({ path, value: parseValue(arg.slice(i + 1)) });
+}
+
+const isIndex = (k: string): boolean => /^\d+$/.test(k);
+
+export function setPath(doc: Json | undefined, path: readonly string[], value: Json): Json {
+  const [k, ...rest] = path;
+  if (k === undefined) return value;
+  if (Array.isArray(doc) && isIndex(k)) {
+    const i = Number(k);
+    return Array.from({ length: Math.max(doc.length, i + 1) }, (_, j): Json => (j === i ? setPath(doc[j], rest, value) : (doc[j] ?? null)));
+  }
+  const base = isMap(doc) ? doc : {};
+  const next = rest.length && base[k] === undefined && isIndex(rest[0] ?? "") ? [] : base[k];
+  return { ...base, [k]: setPath(next, rest, value) };
+}

package/plugins/olko-creative/skills/shorts-animator/scripts/domain/schema.ts

@@ -0,0 +1,81 @@
+// short.json arrives as unknown JSON; this is the one place it is narrowed into a Short.
+import type { Json, JsonMap, Line, Music, Result, Short, Shot, Voice } from "./types.ts";
+import { fail, ok } from "./types.ts";
+
+export const isMap = (x: unknown): x is JsonMap => typeof x === "object" && x !== null && !Array.isArray(x);
+export const isJson = (x: unknown): x is Json =>
+  x === null || ["boolean", "number", "string"].includes(typeof x) || (Array.isArray(x) ? x.every(isJson) : isMap(x) && Object.values(x).every(isJson));
+
+const str = (o: JsonMap, k: string): string | undefined => (typeof o[k] === "string" ? String(o[k]) : undefined);
+const num = (o: JsonMap, k: string): number | undefined => {
+  const v = o[k];
+  return typeof v === "number" ? v : undefined;
+};
+const map = (o: JsonMap, k: string): JsonMap | undefined => {
+  const v = o[k];
+  return isMap(v) ? v : undefined;
+};
+
+const shotOf = (x: Json): Shot | undefined => {
+  if (typeof x === "string") return { scene: x };
+  if (!isMap(x)) return undefined;
+  const scene = str(x, "scene");
+  return scene === undefined
+    ? undefined
+    : { scene, move: str(x, "move"), amount: num(x, "amount"), seed: num(x, "seed"), transition: str(x, "transition") };
+};
+
+const shotsOf = (x: Json | undefined): readonly Shot[] | undefined => {
+  const list = Array.isArray(x) ? x : x === undefined ? [] : [x];
+  const shots = list.map(shotOf);
+  return shots.length > 0 && shots.every((s) => s !== undefined) ? shots.filter((s) => s !== undefined) : undefined;
+};
+
+const lineOf = (x: Json, i: number): Result<Line> => {
+  if (!isMap(x)) return fail(`lines[${i}] is not an object`);
+  const say = typeof x.say === "string" || typeof x.say === "number" ? String(x.say) : undefined;
+  const shots = shotsOf(x.scene);
+  if (say === undefined) return fail(`lines[${i}] has no "say"`);
+  if (shots === undefined) return fail(`lines[${i}] needs "scene": a name, {scene, ...}, or a list of them`);
+  return ok({
+    say, shots, speak: str(x, "speak"), caption: str(x, "caption"), move: str(x, "move"), amount: num(x, "amount"),
+    seed: num(x, "seed"), hold: num(x, "hold"), transition: str(x, "transition"),
+  });
+};
+
+export const DEFAULT_VOICE = { kind: "kokoro", id: "bm_george", speed: 0.92 } satisfies Voice;
+
+const voiceOf = (x: Json | undefined): Voice => {
+  if (x === "none") return { kind: "none" };
+  if (typeof x === "string") return { ...DEFAULT_VOICE, id: x };
+  if (!isMap(x)) return DEFAULT_VOICE;
+  const file = str(x, "file");
+  if (str(x, "id") === "none") return { kind: "none" };
+  if (file !== undefined) return { kind: "file", file };
+  return { kind: "kokoro", id: str(x, "id") ?? DEFAULT_VOICE.id, speed: num(x, "speed") ?? DEFAULT_VOICE.speed };
+};
+
+const musicOf = (x: Json | undefined): Music =>
+  typeof x === "string"
+    ? { mood: x }
+    : isMap(x)
+      ? { mood: str(x, "mood") ?? "tender", volume: num(x, "volume"), seed: num(x, "seed"), start: num(x, "start") }
+      : { mood: "tender" };
+
+const collect = <T>(rs: readonly Result<T>[]): Result<readonly T[]> => {
+  const errors = rs.flatMap((r) => (r.ok ? [] : r.errors));
+  return errors.length ? fail(...errors) : ok(rs.flatMap((r) => (r.ok ? [r.value] : [])));
+};
+
+export function parseShort(raw: unknown): Result<Short> {
+  if (!isMap(raw)) return fail("short.json is not a JSON object");
+  const lines = Array.isArray(raw.lines) ? collect(raw.lines.map(lineOf)) : fail<readonly Line[]>("short.json has no lines");
+  if (!lines.ok) return lines;
+  if (lines.value.length === 0) return fail("short.json has no lines");
+  return ok({
+    title: str(raw, "title") ?? "short", format: str(raw, "format") ?? "9:16", fps: num(raw, "fps") || 24,
+    twos: num(raw, "twos") || 2, lead: num(raw, "lead") ?? 0.35, pause: num(raw, "pause") ?? 0.3, tail: num(raw, "tail") ?? 1.2,
+    transition: str(raw, "transition") ?? "cut", look: raw.look ?? "oil", palette: map(raw, "palette"),
+    captions: map(raw, "captions") ?? {}, voice: voiceOf(raw.voice), music: musicOf(raw.music), lines: lines.value,
+  });
+}

package/plugins/olko-creative/skills/shorts-animator/scripts/domain/timeline.ts

@@ -0,0 +1,75 @@
+// When every shot and caption is on screen. The arithmetic order is load-bearing: renders are compared by hash.
+import { captionChunks } from "./captions.ts";
+import type { Beat, Cue, Line, Result, Short, Take, Timeline } from "./types.ts";
+import { fail, ok } from "./types.ts";
+
+export const FORMATS: Readonly<Record<string, readonly [number, number]>> = {
+  "9:16": [1080, 1920],
+  "16:9": [1920, 1080],
+  "1:1": [1080, 1080],
+  "4:5": [1080, 1350],
+};
+
+type Span = { readonly start: number; readonly speak: number; readonly end: number };
+
+const spanOf = (s: Short, i: number, at: number, take: Take): Span => {
+  const line = s.lines[i];
+  const speak = at + (i === 0 ? s.lead : 0.05);
+  const end = speak + take.dur + s.pause + (line?.hold || 0);
+  return { start: at, speak, end: i === s.lines.length - 1 ? end + s.tail : end };
+};
+
+/** Each caption chunk starts in proportion to the characters before it, across the spoken part. */
+const chunkTimes = (cs: readonly string[], span: Span, take: Take): readonly number[] => {
+  const total = cs.reduce((a, c) => a + c.length + 4, 0);
+  const before = cs.map((_, j) => cs.slice(0, j).reduce((a, c) => a + (c.length + 4), 0));
+  return before.map((acc) => span.speak + (take.dur * acc) / total);
+};
+
+const cuesOf = (cs: readonly string[], times: readonly number[], span: Span): readonly Cue[] =>
+  cs.map((text, j) => ({ at: j === 0 ? span.start : (times[j] ?? 0), end: j === cs.length - 1 ? span.end : (times[j + 1] ?? 0), text }));
+
+/** Up to as many shots as chunks: cut on a chunk. More shots than chunks: cut evenly through the line. */
+const cutsOf = (n: number, times: readonly number[], span: Span): readonly number[] =>
+  Array.from({ length: n }, (_, j) =>
+    j === 0 ? span.start : n <= times.length ? (times[Math.floor((j * times.length) / n)] ?? 0) : span.speak + ((span.end - span.speak) * j) / n,
+  );
+
+const beatsOf = (s: Short, i: number, line: Line, cuts: readonly number[], span: Span): readonly Beat[] =>
+  line.shots.map((shot, j) => {
+    const bs = cuts[j] ?? span.start;
+    const be = j === line.shots.length - 1 ? span.end : (cuts[j + 1] ?? span.end);
+    return {
+      line: i, scene: shot.scene, start: +bs.toFixed(4), dur: +(be - bs).toFixed(4),
+      move: shot.move ?? line.move ?? "push", moveAmount: shot.amount ?? line.amount, seed: shot.seed ?? line.seed,
+      transition: j === 0 ? (line.transition ?? s.transition) : (shot.transition ?? "cut"), say: line.say,
+    };
+  });
+
+type Acc = { readonly t: number; readonly beats: readonly Beat[]; readonly track: readonly Cue[]; readonly voiceAt: readonly number[] };
+
+export function timeline(s: Short, takes: readonly Take[]): Result<Timeline> {
+  const size = FORMATS[s.format];
+  if (!size) return fail(`format ${s.format}? (${Object.keys(FORMATS).join(", ")})`);
+  if (takes.length !== s.lines.length) return fail(`${takes.length} takes for ${s.lines.length} lines`);
+  const maxWords = typeof s.captions.words === "number" ? s.captions.words : 5;
+  const acc = s.lines.reduce<Acc>(
+    (a, line, i) => {
+      const take = takes[i] ?? { file: null, dur: 0 };
+      const span = spanOf(s, i, a.t, take);
+      const cs = captionChunks(line, maxWords);
+      const times = chunkTimes(cs, span, take);
+      const cuts = cutsOf(line.shots.length, times, span);
+      return {
+        t: span.end, beats: [...a.beats, ...beatsOf(s, i, line, cuts, span)],
+        track: [...a.track, ...cuesOf(cs, times, span)], voiceAt: [...a.voiceAt, span.speak],
+      };
+    },
+    { t: 0, beats: [], track: [], voiceAt: [] },
+  );
+  const [W, H] = size;
+  return ok({
+    W, H, fps: s.fps, twos: s.twos, duration: +acc.t.toFixed(3), beats: acc.beats,
+    track: s.captions.style === "none" ? [] : acc.track, voiceAt: acc.voiceAt,
+  });
+}

package/plugins/olko-creative/skills/shorts-animator/scripts/domain/types.ts

@@ -0,0 +1,91 @@
+// The data a short is made of. Maps stay open: unknown keys pass through to the page untouched.
+
+export type Json = null | boolean | number | string | readonly Json[] | { readonly [k: string]: Json };
+export type JsonMap = { readonly [k: string]: Json };
+
+export type Shot = {
+  readonly scene: string;
+  readonly move?: string;
+  readonly amount?: number;
+  readonly seed?: number;
+  readonly transition?: string;
+};
+
+export type Line = {
+  readonly say: string;
+  readonly speak?: string;
+  readonly caption?: string;
+  readonly shots: readonly Shot[];
+  readonly move?: string;
+  readonly amount?: number;
+  readonly seed?: number;
+  readonly hold?: number;
+  readonly transition?: string;
+};
+
+export type Voice =
+  | { readonly kind: "none" }
+  | { readonly kind: "file"; readonly file: string }
+  | { readonly kind: "kokoro"; readonly id: string; readonly speed: number };
+
+export type Music = {
+  readonly mood: string;
+  readonly volume?: number;
+  readonly seed?: number;
+  readonly start?: number;
+};
+
+export type Short = {
+  readonly title: string;
+  readonly format: string;
+  readonly fps: number;
+  readonly twos: number;
+  readonly lead: number;
+  readonly pause: number;
+  readonly tail: number;
+  readonly transition: string;
+  readonly look: Json;
+  readonly palette?: JsonMap;
+  readonly captions: JsonMap;
+  readonly voice: Voice;
+  readonly music: Music;
+  readonly lines: readonly Line[];
+};
+
+/** One narrated line as the timeline needs it: how long it speaks, and where its audio comes from. */
+export type Take = {
+  readonly file: string | null;
+  readonly dur: number;
+  readonly from?: number;
+  readonly slice?: boolean;
+};
+
+export type Beat = {
+  readonly line: number;
+  readonly scene: string;
+  readonly start: number;
+  readonly dur: number;
+  readonly move: string;
+  readonly moveAmount?: number;
+  readonly seed?: number;
+  readonly transition: string;
+  readonly say: string;
+};
+
+export type Cue = { readonly at: number; readonly end: number; readonly text: string };
+
+export type Timeline = {
+  readonly W: number;
+  readonly H: number;
+  readonly fps: number;
+  readonly twos: number;
+  readonly duration: number;
+  readonly beats: readonly Beat[];
+  readonly track: readonly Cue[];
+  readonly voiceAt: readonly number[];
+};
+
+export type Result<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly errors: readonly string[] };
+
+export const ok = <T>(value: T): Result<T> => ({ ok: true, value });
+export const fail = <T>(...errors: readonly string[]): Result<T> => ({ ok: false, errors });

package/plugins/olko-creative/skills/shorts-animator/scripts/edge/chrome.ts

@@ -0,0 +1,169 @@
+// A headless Chrome driven over the DevTools protocol with Node's own WebSocket and fetch:
+// no puppeteer, nothing to npm install.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isMap } from "../domain/schema.ts";
+import type { Json, JsonMap } from "../domain/types.ts";
+
+export type Chrome = { readonly bin: string; readonly shell: boolean };
+export type Page = {
+  readonly evaluate: (expression: string) => Promise<Json | undefined>;
+  readonly logs: () => readonly string[];
+  readonly close: () => void;
+};
+
+const SHELL = process.platform === "win32" ? "chrome-headless-shell.exe" : "chrome-headless-shell";
+const SYSTEM: Readonly<Record<string, readonly string[]>> = {
+  darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"],
+  linux: ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser"],
+  win32: [
+    `${process.env["PROGRAMFILES"]}\\Google\\Chrome\\Application\\chrome.exe`,
+    `${process.env["PROGRAMFILES(X86)"]}\\Google\\Chrome\\Application\\chrome.exe`,
+    `${process.env["PROGRAMFILES(X86)"]}\\Microsoft\\Edge\\Application\\msedge.exe`,
+  ],
+};
+
+const dirs = (d: string): readonly string[] =>
+  fs.existsSync(d) ? fs.readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(d, e.name)) : [];
+
+/** The headless shell HyperFrames downloads, newest first. */
+const hyperframesShell = (): string | undefined =>
+  dirs(path.join(os.homedir(), ".cache/hyperframes/chrome/chrome-headless-shell"))
+    .toSorted()
+    .reverse()
+    .flatMap((v) => dirs(v).map((sub) => path.join(sub, SHELL)))
+    .find((f) => fs.existsSync(f));
+
+export function findChrome(): Chrome | undefined {
+  const env = process.env.CHROME;
+  if (env && fs.existsSync(env)) return { bin: env, shell: /headless-shell/.test(env) };
+  const hf = hyperframesShell();
+  if (hf) return { bin: hf, shell: true };
+  const sys = (SYSTEM[process.platform] ?? []).find((c) => fs.existsSync(c));
+  return sys ? { bin: sys, shell: false } : undefined;
+}
+
+const flags = (c: Chrome, profile: string, width: number, height: number): readonly string[] => {
+  // the GPU through Metal on a Mac is ~15x faster than the software fallback
+  const angle = process.env.SHORTS_GL || (process.platform === "darwin" ? "metal" : "");
+  return [
+    "--remote-debugging-port=0", `--user-data-dir=${profile}`, "--no-first-run", "--no-default-browser-check",
+    "--allow-file-access-from-files", "--hide-scrollbars", "--mute-audio", "--enable-webgl", "--ignore-gpu-blocklist",
+    `--window-size=${width},${height}`, ...(c.shell ? [] : ["--headless=new"]), ...(angle ? [`--use-angle=${angle}`] : []), "about:blank",
+  ];
+};
+
+const field = (o: Json | undefined, ...keys: readonly string[]): Json | undefined =>
+  keys.reduce<Json | undefined>((v, k) => (isMap(v) ? v[k] : undefined), o);
+
+const parse = (data: unknown): JsonMap | undefined => {
+  try {
+    const v: unknown = typeof data === "string" ? JSON.parse(data) : undefined;
+    return isMap(v) ? v : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** What the page printed: console calls and uncaught exceptions. */
+const logLine = (m: JsonMap): string | undefined => {
+  if (m.method === "Runtime.consoleAPICalled") {
+    const args = field(m, "params", "args");
+    return Array.isArray(args) ? args.map((a) => String(field(a, "value") ?? field(a, "description") ?? "")).join(" ") : "";
+  }
+  if (m.method !== "Runtime.exceptionThrown") return undefined;
+  return "ERROR " + String(field(m, "params", "exceptionDetails", "exception", "description") ?? field(m, "params", "exceptionDetails", "text") ?? "");
+};
+
+const devtoolsUrl = (proc: ReturnType<typeof spawn>): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const seen: string[] = [];
+    const to = setTimeout(() => reject(new Error("Chrome didn't start:\n" + seen.join("").slice(-800))), 30000);
+    proc.stderr?.on("data", (d) => {
+      seen.push(String(d));
+      const m = seen.join("").match(/DevTools listening on (ws:\/\/\S+)/);
+      if (m?.[1]) { clearTimeout(to); resolve(m[1]); }
+    });
+    proc.on("exit", (c) => { clearTimeout(to); reject(new Error(`Chrome exited (${c}):\n` + seen.join("").slice(-800))); });
+  });
+
+const pageSocketUrl = async (browserWs: string): Promise<string> => {
+  const list: unknown = await (await fetch(`http://127.0.0.1:${new URL(browserWs).port}/json/list`)).json();
+  const pg = Array.isArray(list) ? list.find((t) => isMap(t) && t.type === "page") : undefined;
+  const url = isMap(pg) ? pg.webSocketDebuggerUrl : undefined;
+  if (typeof url !== "string") throw new Error("Chrome opened no page");
+  return url;
+};
+
+type Wire = { readonly send: (method: string, params?: JsonMap) => Promise<JsonMap>; readonly logs: () => readonly string[]; readonly ws: WebSocket };
+
+/** The one stateful edge: replies waiting on an id, and the page's log. */
+async function connect(url: string): Promise<Wire> {
+  const ws = new WebSocket(url);
+  await new Promise((r, j) => { ws.onopen = r; ws.onerror = j; });
+  const pending = new Map<number, (m: JsonMap) => void>();
+  const logs: string[] = [];
+  const ids = { next: 0 };
+  ws.onmessage = (ev) => {
+    const m = parse(ev.data);
+    if (!m) return;
+    const id = typeof m.id === "number" && pending.has(m.id) ? m.id : undefined;
+    if (id !== undefined) { const reply = pending.get(id); pending.delete(id); reply?.(m); return; }
+    const line = logLine(m);
+    if (line !== undefined) logs.push(line);
+  };
+  const send = (method: string, params: JsonMap = {}) =>
+    new Promise<JsonMap>((r) => {
+      const id = ++ids.next;
+      pending.set(id, r);
+      ws.send(JSON.stringify({ id, method, params }));
+    });
+  return { send, logs: () => logs, ws };
+}
+
+const evaluator = (send: Wire["send"]) => async (expression: string): Promise<Json | undefined> => {
+  const r = await send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+  const ex = field(r, "result", "exceptionDetails");
+  if (ex !== undefined) throw new Error(String(field(ex, "exception", "description") ?? field(ex, "text")));
+  if (r.error !== undefined) throw new Error(String(field(r, "error", "message")));
+  return field(r, "result", "result", "value");
+};
+
+async function waitFor(evaluate: Page["evaluate"], expr: string, deadline: number, logs: () => readonly string[]): Promise<void> {
+  const ok = await evaluate(expr).catch(() => false);
+  if (ok === true) return;
+  if (Date.now() > deadline) throw new Error("The page didn't load:\n" + logs().join("\n"));
+  await new Promise((r) => setTimeout(r, 100));
+  return waitFor(evaluate, expr, deadline, logs);
+}
+
+export async function openPage(url: string, width: number, height: number, readyWhen = "window.ready === true"): Promise<Page> {
+  const c = findChrome();
+  if (!c) throw new Error("No Chrome found. Install Google Chrome, run `npx --yes hyperframes@0.8.150 browser ensure`, or set CHROME=/path/to/chrome");
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), "shorts-chrome-"));
+  const proc = spawn(c.bin, flags(c, profile, width, height), { stdio: ["ignore", "ignore", "pipe"] });
+  const close = () => {
+    proc.kill("SIGKILL");
+    // A killed Chrome can still be flushing its profile, so retry, and leave it to the OS if it will not go.
+    try {
+      fs.rmSync(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    } catch {
+      console.error(`· could not remove the browser profile at ${profile}`);
+    }
+  };
+  try {
+    const wire = await connect(await pageSocketUrl(await devtoolsUrl(proc)));
+    await wire.send("Runtime.enable");
+    await wire.send("Page.enable");
+    await wire.send("Emulation.setDeviceMetricsOverride", { width: Math.min(width, 1600), height: Math.min(height, 1600), deviceScaleFactor: 1, mobile: false });
+    await wire.send("Page.navigate", { url });
+    const evaluate = evaluator(wire.send);
+    await waitFor(evaluate, readyWhen, Date.now() + 30000, wire.logs);
+    return { evaluate, logs: wire.logs, close: () => { wire.ws.close(); close(); } };
+  } catch (e) {
+    close();
+    throw e;
+  }
+}

package/plugins/olko-creative/skills/shorts-animator/scripts/edge/doctor.ts

@@ -0,0 +1,52 @@
+// `SA doctor`: checks what the pipeline needs, sets up the narrator, and renders a 3-second test short.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findChrome } from "./chrome.ts";
+import { has } from "./media.ts";
+import { HYPERFRAMES, setupNarrator } from "./voice.ts";
+
+const FFMPEG_HINT: Readonly<Record<string, string>> = { darwin: "brew install ffmpeg", win32: "winget install ffmpeg" };
+const TEST_SCENE = `window.SCENES = { test: (k) => { k.sky({ stops: ["#3f8ad6", "#e6eef2"] }); k.clouds({}); k.ground({ y: 0.6, color: "#58a531", stripes: 12 }); k.person({ x: 0.5, y: 0.82, h: 0.26, pose: "wave" }); } };`;
+
+type Check = { readonly ok: boolean; readonly msg: string };
+const say = (c: Check): Check => (console.log(`${c.ok ? "ok" : "!!"} ${c.msg}`), c);
+
+const node = (): Check => {
+  const v = process.versions.node;
+  const [major = 0, minor = 0] = v.split(".").map(Number);
+  // .ts runs without a flag from 22.18 (type stripping)
+  return major > 22 || (major === 22 && minor >= 18) ? { ok: true, msg: `Node ${v}` } : { ok: false, msg: `Node ${v} is too old: install Node 22.18+ from https://nodejs.org` };
+};
+
+const ffmpeg = (): Check =>
+  has("ffmpeg") ? { ok: true, msg: "ffmpeg" } : { ok: false, msg: `ffmpeg is missing: ${FFMPEG_HINT[process.platform] ?? "sudo apt install ffmpeg"}` };
+
+const chrome = (): Check => {
+  const found = findChrome() ?? (console.log("· no Chrome found, fetching the headless one HyperFrames uses..."),
+    spawnSync(process.platform === "win32" ? "npx.cmd" : "npx", ["--yes", HYPERFRAMES, "browser", "ensure"], { stdio: "inherit" }), findChrome());
+  return found ? { ok: true, msg: `Chrome: ${found.bin}` } : { ok: false, msg: `no Chrome: install Google Chrome, or run npx --yes ${HYPERFRAMES} browser ensure` };
+};
+
+function testRender(cli: string, withVoice: boolean): Check {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "shorts-test-"));
+  fs.writeFileSync(path.join(work, "short.json"), JSON.stringify({
+    title: "test", look: "oil", voice: withVoice ? { id: "bm_george" } : "none", music: { mood: "tender" },
+    lines: [{ say: "It works.", scene: "test", move: "push" }], tail: 1,
+  }));
+  fs.writeFileSync(path.join(work, "scenes.js"), TEST_SCENE);
+  const r = spawnSync(process.execPath, [cli, "render", work], { stdio: "inherit" });
+  const mp4 = path.join(work, "test.mp4");
+  return r.status === 0 && fs.existsSync(mp4) ? { ok: true, msg: `test short: ${mp4}` } : { ok: false, msg: "the test render failed (see above)" };
+}
+
+/** Returns the exit code. */
+export async function doctor(cli: string): Promise<number> {
+  const basics = [node, ffmpeg, chrome].map((c) => say(c()));
+  if (basics.some((c) => !c.ok)) return 1;
+  const why = await setupNarrator();
+  const voice = say(why ? { ok: false, msg: why } : { ok: true, msg: "the narrator (Kokoro, runs on this computer)" });
+  const render = say(testRender(cli, voice.ok));
+  return voice.ok && render.ok ? 0 : 1;
+}