@jokerized/decksmith 0.1.0

package/dist/server/options.js

@@ -0,0 +1,198 @@
+import {
+  canvasProblem,
+  canvasWarnings,
+  FORMATS,
+  LEGIBLE_W,
+  MAX_ASPECT,
+  MAX_EDGE,
+  MIN_EDGE,
+  prefsSchema,
+  resizeFormat,
+  THEME_NAMES
+} from "../index.js";
+import { UploadError } from "./upload.js";
+const MAX_PIXELS = 4e6;
+const MAX_SIDE = Math.min(
+  MAX_EDGE,
+  16 * Math.floor(Math.sqrt(MAX_PIXELS * MAX_ASPECT) / 16)
+);
+function formatCatalog() {
+  return Object.entries(FORMATS).map(([id, f]) => ({
+    id,
+    width: f.width,
+    height: f.height,
+    navigable: f.navigable,
+    // JSON has no Infinity; null reads as "no ceiling", which is what it means.
+    maxSeconds: f.maxSeconds === void 0 || !Number.isFinite(f.maxSeconds) ? null : f.maxSeconds
+  }));
+}
+function catalog() {
+  return {
+    formats: formatCatalog(),
+    themes: THEME_NAMES,
+    tones: ["plain", "academic", "conversational", "punchy"],
+    densities: ["sparse", "normal", "dense"],
+    /** How many of a beat's stops speak. A different axis from `densities`. */
+    narrationDensities: ["high", "medium", "low"],
+    slides: { min: 3, max: 40, default: prefsSchema.parse({}).slides },
+    /** `null` default: no target, which is what every deck did before this. */
+    duration: { min: 10, max: 1800, default: null },
+    speed: { min: 0.25, max: 3, default: 1 },
+    // The picker enforces exactly these, so a size the page offers is a size
+    // this server will build. They were three different tables until the UI's
+    // own maximum came back 400 from the server it posts to.
+    canvas: {
+      minSide: MIN_EDGE,
+      maxSide: MAX_SIDE,
+      maxPixels: MAX_PIXELS,
+      maxAspect: MAX_ASPECT,
+      /** Below this a deck lays out but is not legible. A warning, never a refusal. */
+      legibleWidth: LEGIBLE_W
+    },
+    defaults: { format: "deck-16x9", narrate: false, video: false }
+  };
+}
+function parseOptions(fields) {
+  const warnings = [];
+  const formatId = str(fields.format) ?? "deck-16x9";
+  const preset = FORMATS[formatId];
+  if (!preset) {
+    throw new UploadError(
+      `Unknown format "${formatId}".`,
+      `Choose one of: ${Object.keys(FORMATS).join(", ")}. GET /api/formats lists their sizes.`
+    );
+  }
+  const format = withCanvas(preset, fields, warnings);
+  const patch = {};
+  if (str(fields.theme) !== void 0) patch.theme = requireTheme(str(fields.theme));
+  if (str(fields.slides) !== void 0) patch.slides = int("slides", fields.slides);
+  if (str(fields.lang) !== void 0) patch.lang = requireLang(str(fields.lang));
+  if (str(fields.tone) !== void 0) patch.tone = str(fields.tone);
+  if (str(fields.density) !== void 0) patch.density = str(fields.density);
+  if (str(fields.duration) !== void 0)
+    patch.duration = num("duration", fields.duration);
+  if (str(fields.speed) !== void 0) patch.animationSpeed = num("speed", fields.speed);
+  const narrateWanted = bool(fields.narrate) ?? false;
+  const video = bool(fields.video) ?? false;
+  const narrate = narrateWanted || video;
+  if (video && !narrateWanted)
+    warnings.push("video needs narration to time itself, so narration was turned on");
+  const narration = { enabled: narrate };
+  if (str(fields.voice) !== void 0) narration.voice = requireVoice(str(fields.voice));
+  if (str(fields.narrationDensity) !== void 0) narration.density = str(fields.narrationDensity);
+  patch.narration = narration;
+  const parsed = prefsSchema.safeParse(patch);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    const where = issue?.path.join(".") || "options";
+    throw new UploadError(
+      `${where}: ${issue?.message ?? "is not a valid option"}.`,
+      "GET /api/formats lists every option and the range it accepts."
+    );
+  }
+  return {
+    format,
+    formatId,
+    prefs: parsed.data,
+    narrate,
+    video,
+    stated: { theme: patch.theme !== void 0, lang: patch.lang !== void 0 },
+    warnings
+  };
+}
+function withCanvas(preset, fields, warnings) {
+  const hasW = str(fields.width) !== void 0;
+  const hasH = str(fields.height) !== void 0;
+  if (!hasW && !hasH) return preset;
+  if (hasW !== hasH) {
+    throw new UploadError(
+      "width and height must be given together.",
+      `Send both, or neither and let the "${preset.id}" preset decide.`
+    );
+  }
+  const width = even("width", fields.width, warnings);
+  const height = even("height", fields.height, warnings);
+  const problem = canvasProblem(width, height);
+  if (problem) {
+    throw new UploadError(
+      problem.replace(/--/g, ""),
+      `Canvases run ${MIN_EDGE}\u2013${MAX_SIDE}px a side, up to ${MAX_PIXELS / 1e6} megapixels, between 1:${MAX_ASPECT} and ${MAX_ASPECT}:1. GET /api/formats states all of it.`
+    );
+  }
+  if (width * height > MAX_PIXELS) {
+    throw new UploadError(
+      `${width}\xD7${height} is ${(width * height / 1e6).toFixed(1)} megapixels, over this server's ${MAX_PIXELS / 1e6} megapixel ceiling.`,
+      "Pick a smaller canvas; capture holds whole frames in memory and this box is shared."
+    );
+  }
+  warnings.push(...canvasWarnings(width, height));
+  return resizeFormat(preset, width, height);
+}
+function even(name, raw, warnings) {
+  const n = int(name, raw);
+  if (n % 2 === 0 || !Number.isFinite(n)) return n;
+  warnings.push(`${name} ${n} rounded down to ${n - 1}; h264 needs even dimensions`);
+  return n - 1;
+}
+function requireTheme(value) {
+  if (!THEME_NAMES.includes(value)) {
+    throw new UploadError(`Unknown theme "${value}".`, `Choose one of: ${THEME_NAMES.join(", ")}.`);
+  }
+  return value;
+}
+function requireLang(value) {
+  if (!/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8}){0,3}$/.test(value)) {
+    throw new UploadError(
+      `"${value}" is not a language tag.`,
+      'Use a BCP-47 tag such as "en", "ko" or "en-GB".'
+    );
+  }
+  return value;
+}
+function requireVoice(value) {
+  if (!/^[A-Za-z]{2,3}-[A-Za-z0-9-]{2,40}Neural$/.test(value)) {
+    throw new UploadError(
+      `"${value}" is not an edge-tts voice id.`,
+      'Voice ids look like "en-US-AvaMultilingualNeural". Leave it unset to get one chosen for the language and tone.'
+    );
+  }
+  return value;
+}
+function str(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+}
+function bool(value) {
+  const v = str(value)?.toLowerCase();
+  if (v === void 0) return void 0;
+  if (["1", "true", "on", "yes"].includes(v)) return true;
+  if (["0", "false", "off", "no"].includes(v)) return false;
+  throw new UploadError(`"${value}" is not a yes or no.`, "Send true or false.");
+}
+function num(name, raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) {
+    throw new UploadError(
+      `${name} expects a number, got "${raw}".`,
+      "Send a plain decimal number."
+    );
+  }
+  return n;
+}
+function int(name, raw) {
+  const n = num(name, raw);
+  if (!Number.isInteger(n)) {
+    throw new UploadError(
+      `${name} expects a whole number, got "${raw}".`,
+      "Drop the decimal point."
+    );
+  }
+  return n;
+}
+export {
+  MAX_PIXELS,
+  MAX_SIDE,
+  catalog,
+  formatCatalog,
+  parseOptions
+};

package/dist/server/pipeline.js

@@ -0,0 +1,356 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  assertRefsResolve,
+  buildDeck,
+  codexPlanner,
+  durationPlan,
+  fetchFigures,
+  narrate,
+  PACK_VERSION,
+  parseMarkdown,
+  planMedia,
+  render,
+  writePack
+} from "../index.js";
+import {
+  insideRoot,
+  looksLikeZip,
+  MARKDOWN_EXTS,
+  pickMarkdown,
+  readZip,
+  UploadError
+} from "./upload.js";
+const AUDIO_DIR = "audio";
+const NARRATION_FILE = "narration.json";
+const MAX_REMOTE_FIGURES = 40;
+const FEED_FORMATS = /* @__PURE__ */ new Set(["short-9x16", "post-1x1"]);
+function stagesFor(options) {
+  const stages = ["ingest", "plan"];
+  if (options.narrate) stages.push("narrate");
+  stages.push("build");
+  if (options.video) stages.push("render");
+  return stages;
+}
+async function runPipeline(job, input) {
+  const { options } = input;
+  const dirs = {
+    upload: join(job.dir, "upload"),
+    src: join(job.dir, "src"),
+    audio: join(job.dir, AUDIO_DIR),
+    deck: join(job.dir, "deck")
+  };
+  const warnings = [...options.warnings];
+  const url = (rel) => `/d/${job.id}/${rel}`;
+  job.begin("ingest");
+  const source = await ingest(job, input, dirs, warnings);
+  const dropped = warnings.filter((w) => w.startsWith("figure ")).length;
+  job.done(
+    "ingest",
+    `${source.sections.length} sections, ${source.figures.length} figures${dropped > 0 ? ` (${dropped} left out)` : ""}`
+  );
+  job.begin("plan");
+  job.log("plan: asking Codex for a storyboard \u2014 this is the slow one, about a minute");
+  const prefs = options.stated.lang ? options.prefs : { ...options.prefs, lang: source.lang };
+  const planned = await codexPlanner(source, { prefs });
+  const storyboard = {
+    ...planned,
+    lang: prefs.lang,
+    theme: options.stated.theme ? prefs.theme : planned.theme
+  };
+  assertRefsResolve(storyboard, source);
+  await writeJson(join(job.dir, "storyboard.json"), storyboard);
+  job.done("plan", `${storyboard.beats.length} beats`);
+  let narration;
+  if (options.narrate) {
+    job.begin("narrate");
+    const speaking = storyboard.beats.filter((b) => b.narration?.trim()).length;
+    if (speaking === 0) {
+      job.skip("narrate", "no beat came back with narration text");
+      warnings.push("the plan had nothing to say aloud, so the deck is silent");
+    } else {
+      job.log(`narrate: ${speaking} of ${storyboard.beats.length} beats speak`);
+      await mkdir(dirs.audio, { recursive: true });
+      const spoken = await narrate(storyboard, source, prefs, {
+        dir: dirs.audio,
+        format: options.format
+      });
+      await writeJson(join(dirs.audio, NARRATION_FILE), spoken);
+      narration = { voice: spoken.voice, dir: AUDIO_DIR, beats: spoken.beats };
+      const segments = Object.values(spoken.beats).flat();
+      const seconds = segments.reduce((sum, s) => sum + s.seconds, 0);
+      job.done("narrate", `${segments.length} segments, ${seconds.toFixed(1)}s in ${spoken.voice}`);
+    }
+  }
+  job.begin("build");
+  const paced = durationPlan(prefs);
+  for (const w of paced.warnings) warnings.push(w);
+  const built = await buildDeck(storyboard, source, dirs.deck, {
+    format: options.format,
+    theme: options.stated.theme ? prefs.theme : storyboard.theme,
+    // The DURATION target owns the pace when there is one, and is `animationSpeed`
+    // itself when there is not. Its warnings are the job's: a target that cannot
+    // be met is something the person who asked for it must be told.
+    speed: paced.speed,
+    assetsFrom: dirs.src,
+    ...narration ? { narration, audioFrom: dirs.audio } : {},
+    onStep: (line) => job.log(line),
+    // A beat the planner over-filled costs that slide, not the deck. Named in
+    // the warnings so the result says what is missing rather than quietly
+    // showing eleven slides where twelve were planned.
+    onBeatError: (id, err) => {
+      warnings.push(`slide ${id} was left out: ${err.message}`);
+      job.log(`build: dropped ${id} \u2014 ${err.message}`);
+    }
+  });
+  for (const d of built.cut.dropped) warnings.push(`cut ${d.beat.id} \u2014 ${d.reason}`);
+  for (const d of built.cut.dangling) warnings.push(`check the wording \u2014 ${d.reason}`);
+  const packUrl = await pack(job, { storyboard, source, prefs, narration, dirs, url });
+  job.done(
+    "build",
+    `${built.cut.kept.length} beats at ${options.format.width}\xD7${options.format.height}`
+  );
+  let videoUrl;
+  let srtUrl;
+  let duration = built.cut.seconds;
+  if (options.video) {
+    job.begin("render");
+    if (!narration) {
+      job.skip("render", "there is no narration to time the video against");
+      warnings.push("no video: a render needs narration for its timing manifest");
+    } else {
+      job.log("render: capturing frames \u2014 two minutes for a four-minute video");
+      const out = await render({
+        deck: dirs.deck,
+        out: join(dirs.deck, "video.mp4"),
+        subtitles: "sidecar",
+        log: (line) => job.log(line),
+        // The last of the three length levers, and the only one that acts on a
+        // finished file. Plan time already spent the budget on what gets said;
+        // this closes whatever gap survived it, and says what it cost.
+        ...prefs.duration ? { targetSeconds: prefs.duration } : {}
+      });
+      videoUrl = url("video.mp4");
+      if (out.srt) srtUrl = url(relative(dirs.deck, out.srt).split("\\").join("/"));
+      duration = out.seconds;
+      if (out.playback > 1) {
+        warnings.push(
+          `playback was sped up ${out.playback}\xD7 to reach the ${prefs.duration}s target; the audio is time-stretched, not re-spoken`
+        );
+      }
+      if (!out.burned && out.srt && FEED_FORMATS.has(options.formatId)) {
+        warnings.push(
+          `captions are a separate ${relative(dirs.deck, out.srt)} \u2014 feed platforms discard an uploaded .srt, so for a short run \`decksmith render --subtitles burn\` to put them in the picture`
+        );
+      }
+      job.done("render", `${out.frames} frames, ${out.seconds.toFixed(1)}s`);
+    }
+  }
+  if (!built.navigable) {
+    warnings.push(
+      `${options.formatId} renders linearly, so the deck opens as index.html with no navigation`
+    );
+  }
+  return {
+    deckUrl: url(built.navigable ? "deck.html" : "index.html"),
+    ...videoUrl ? { videoUrl } : {},
+    ...srtUrl ? { srtUrl } : {},
+    ...packUrl ? { packUrl } : {},
+    slides: built.cut.kept.length,
+    duration: Math.round(duration * 1e3) / 1e3,
+    warnings
+  };
+}
+async function ingest(job, input, dirs, warnings) {
+  await mkdir(dirs.upload, { recursive: true });
+  const root = resolve(dirs.upload);
+  let docPath;
+  if (looksLikeZip(input.upload.bytes)) {
+    const { files, warnings: zipWarnings } = readZip(input.upload.bytes);
+    warnings.push(...zipWarnings);
+    for (const [rel, bytes] of Object.entries(files)) {
+      const to = resolve(join(root, rel));
+      if (!insideRoot(root, to))
+        throw new UploadError(`Refusing to write ${rel}.`, "Re-zip from inside the folder.");
+      await mkdir(dirname(to), { recursive: true });
+      await writeFile(to, bytes);
+    }
+    docPath = join(root, pickMarkdown(files));
+    job.log(
+      `ingest: unpacked ${Object.keys(files).length} file(s), reading ${pickMarkdown(files)}`
+    );
+  } else {
+    const ext = (input.upload.filename.match(/\.[^.\\/]+$/)?.[0] ?? "").toLowerCase();
+    if (ext && !MARKDOWN_EXTS.includes(ext)) {
+      throw new UploadError(
+        `"${input.upload.filename}" is a ${ext} file.`,
+        `DeckSmith reads ${MARKDOWN_EXTS.join(", ")} or a .zip containing one. Export the document to markdown first.`
+      );
+    }
+    docPath = join(root, "document.md");
+    await writeFile(docPath, input.upload.bytes);
+  }
+  const text = await readFile(docPath, "utf8");
+  const parsed = parseMarkdown(text, {
+    lang: input.options.stated.lang ? input.options.prefs.lang : void 0
+  });
+  if (parsed.sections.length === 0) {
+    throw new UploadError(
+      "The document has no readable content.",
+      "It parsed to nothing \u2014 check that you uploaded the markdown and not an empty or binary file."
+    );
+  }
+  if (parsed.sections.every((s) => s.heading.trim() === "")) {
+    throw new UploadError(
+      "The document has no headings, so there is nothing to structure a deck around.",
+      "Add at least one `# Heading`. DeckSmith plans one beat per idea and headings are how it finds them."
+    );
+  }
+  job.log(
+    `ingest: ${parsed.sections.length} sections, ${parsed.figures.length} figures, ${parsed.equations.length} equations, ${parsed.tables.length} tables`
+  );
+  const guarded = await guardFigures(parsed, root, input.fetchRemoteFigures, warnings);
+  const source = await fetchFigures(guarded, join(resolve(dirs.src), "assets"));
+  await writeJson(join(dirs.src, "source.json"), source);
+  return source;
+}
+const BLOCKED = [
+  /^10\./,
+  /^127\./,
+  /^169\.254\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^192\.168\./,
+  /^0\./
+];
+async function reachable(url) {
+  let host2;
+  try {
+    host2 = new URL(url).hostname;
+  } catch {
+    return "is not a URL this server can parse";
+  }
+  const bare = host2.replace(/^\[|\]$/g, "");
+  const addrs = [];
+  try {
+    const { lookup } = await import("node:dns/promises");
+    for (const a of await lookup(bare, { all: true })) addrs.push(a.address);
+  } catch {
+    return "does not resolve";
+  }
+  for (const addr of addrs) {
+    if (BLOCKED.some((re) => re.test(addr))) return `resolves to a private address (${addr})`;
+    const v6 = addr.toLowerCase();
+    if (v6 === "::1" || v6.startsWith("fe80:") || v6.startsWith("fc") || v6.startsWith("fd")) {
+      return `resolves to a private address (${addr})`;
+    }
+  }
+  return addrs.length === 0 ? "does not resolve" : null;
+}
+async function guardFigures(source, root, allowRemote, warnings) {
+  const figures = [];
+  let remote = 0;
+  for (const figure of source.figures) {
+    const src = figure.src.trim();
+    const scheme = src.match(/^([a-z][a-z0-9+.-]*):/i)?.[1]?.toLowerCase();
+    if (scheme === "http" || scheme === "https") {
+      if (!allowRemote) {
+        warnings.push(
+          `figure ${figure.id} was left out: it is hosted at ${host(src)} and this server does not fetch remote figures`
+        );
+        continue;
+      }
+      if (++remote > MAX_REMOTE_FIGURES) {
+        warnings.push(
+          `figure ${figure.id} was left out: more than ${MAX_REMOTE_FIGURES} remote figures`
+        );
+        continue;
+      }
+      const why = await reachable(src);
+      if (why) {
+        warnings.push(`figure ${figure.id} was left out: ${host(src)} ${why}`);
+        continue;
+      }
+      figures.push(figure);
+      continue;
+    }
+    if (scheme) {
+      warnings.push(`figure ${figure.id} was left out: "${scheme}:" figures are not read`);
+      continue;
+    }
+    const abs = resolve(join(root, src.replace(/^\.?\//, "")));
+    if (!insideRoot(root, abs)) {
+      warnings.push(`figure ${figure.id} was left out: "${src}" points outside the upload`);
+      continue;
+    }
+    if (!(await stat(abs).catch(() => null))?.isFile()) {
+      warnings.push(`figure ${figure.id} was left out: "${src}" is not in the upload`);
+      continue;
+    }
+    figures.push({ ...figure, src: abs });
+  }
+  return { ...source, figures };
+}
+async function pack(job, ctx) {
+  try {
+    const assets = join(resolve(ctx.dirs.src), "assets");
+    const requests = ctx.source.figures.map((f) => ({
+      id: f.id,
+      url: join(assets, f.src),
+      prefer: "bake"
+    }));
+    const plan = await planMedia(requests, async (url) => ({
+      bytes: new Uint8Array(await readFile(url))
+    }));
+    const files = { ...plan.files };
+    if (ctx.narration) {
+      for (const name of audioNames(ctx.narration)) {
+        files[`${AUDIO_DIR}/${name}`] = new Uint8Array(await readFile(join(ctx.dirs.audio, name)));
+      }
+    }
+    const container = {
+      version: PACK_VERSION,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      title: ctx.storyboard.title,
+      prefs: {
+        ...ctx.prefs,
+        narration: { ...ctx.prefs.narration, enabled: ctx.narration !== void 0 }
+      },
+      source: ctx.source,
+      storyboard: ctx.storyboard,
+      ...ctx.narration ? { narration: await readJson(join(ctx.dirs.audio, NARRATION_FILE)) } : {},
+      media: plan.media
+    };
+    const bytes = await writePack(container, files, join(ctx.dirs.deck, "deck.deck"));
+    job.log(`pack: ${Math.round(bytes / 1024)} KB \u2192 deck.deck`);
+    return ctx.url("deck.deck");
+  } catch (err) {
+    job.log(`pack: skipped \u2014 ${err instanceof Error ? err.message : String(err)}`);
+    return void 0;
+  }
+}
+function audioNames(narration) {
+  return [
+    ...new Set(
+      Object.values(narration.beats).flat().map((s) => s.audio)
+    )
+  ].sort();
+}
+function host(src) {
+  try {
+    return new URL(src).host;
+  } catch {
+    return "another host";
+  }
+}
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+export {
+  runPipeline,
+  stagesFor
+};