@prestyj/cli 5.28.1 → 5.29.0

package/assets/motion/bin/contact-sheet.mjs

@@ -17,7 +17,9 @@ function fail(message) {
 }
 
 const args = process.argv.slice(2);
-const positional = args.filter((a, i) => !a.startsWith("--") && !args[i - 1]?.match(/^--(cols|width)$/));
+const positional = args.filter(
+  (a, i) => !a.startsWith("--") && !args[i - 1]?.match(/^--(cols|width)$/),
+);
 const [framesArg, outArg] = positional;
 if (!framesArg || !outArg) {
   fail("usage: contact-sheet.mjs <frames-dir> <out.jpg> [--cols 4] [--width 1600] [--phone]");
@@ -39,13 +41,17 @@ try {
   const hfPkg = require.resolve("hyperframes/package.json");
   sharp = createRequire(hfPkg)("sharp");
 } catch {
-  fail("Contact sheets need the HyperFrames bundled with EZ. Reinstall EZ Coder to restore Motion mode.");
+  fail(
+    "Contact sheets need the HyperFrames bundled with EZ. Reinstall EZ Coder to restore Motion mode.",
+  );
 }
 
 const framesDir = resolve(framesArg);
 const names = await readdir(framesDir).catch(() => fail(`Frames folder not found: ${framesDir}`));
 // Skip sheets from earlier runs (snapshot writes contact-sheet.jpg beside its frames).
-const entries = names.filter((n) => /\.(png|jpe?g|webp)$/i.test(n) && !/contact-sheet|phone-strip/i.test(n));
+const entries = names.filter(
+  (n) => /\.(png|jpe?g|webp)$/i.test(n) && !/contact-sheet|phone-strip/i.test(n),
+);
 if (entries.length === 0) fail(`No frame images in ${framesDir}`);
 const order = (name) => {
   const m = basename(name, extname(name)).match(/(\d+(?:\.\d+)?)(?!.*\d)/);

package/assets/motion/bin/cues.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+// EZ Motion cue export: load a composition the way a render does and write the
+// sound cues its script marked with `kit.cue(tl, at, sfx)` to a JSON file that
+// score-synth reads (`"cues": "cues.json"` in the score). Retime the animation,
+// export again, and every sound moves with its event.
+//
+// Usage: node cues.mjs <project-dir> [--out <cues.json>] [--composition <file.html>]
+// Default out: <project>/cues.json. Prints a one-line JSON summary.
+//
+// The page is served read-only from 127.0.0.1 to HyperFrames' own Chrome
+// (`hf browser path`), driven over DevTools by HyperFrames' own puppeteer-core,
+// which runs the script and returns the finished DOM. (Chrome's one-shot
+// `--dump-dom` hangs in a full Chrome build on macOS, the fallback when the
+// managed headless shell is missing.)
+import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { mkdtemp, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+const here = dirname(fileURLToPath(import.meta.url));
+export const CUES_VERSION = 1;
+const MAX_CUES = 2000;
+const MAX_AIR_SAMPLES = 50 * 60 * 15;
+const MAX_DOM_BYTES = 64 * 1024 * 1024;
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".wav": "audio/wav",
+  ".mp3": "audio/mpeg",
+};
+
+const ENTITIES = { quot: '"', amp: "&", lt: "<", gt: ">", apos: "'", "#39": "'", "#34": '"' };
+
+/**
+ * Validate one cue list as the kit writes it.
+ * @param {unknown} list
+ * @returns {{ t: number; sfx: string; gain: number; pan: number; send?: number; name?: string }[]}
+ */
+export function validateCues(list) {
+  if (!Array.isArray(list)) throw new Error("cues must be a list");
+  if (list.length > MAX_CUES) throw new Error(`more than ${MAX_CUES} cues`);
+  return list.map((cue, index) => {
+    if (!cue || typeof cue !== "object") throw new Error(`cue ${index} is not an object`);
+    const { t, sfx, gain = 1, pan = 0, send, name } = cue;
+    if (!(typeof t === "number" && Number.isFinite(t) && t >= 0))
+      throw new Error(`cue ${index}: t must be a time >= 0`);
+    if (typeof sfx !== "string" || !/^[a-z][a-z-]*$/.test(sfx))
+      throw new Error(`cue ${index}: sfx must be a sound name`);
+    if (!(typeof gain === "number" && gain >= 0 && gain <= 2))
+      throw new Error(`cue ${index}: gain must be 0..2`);
+    if (!(typeof pan === "number" && pan >= -1 && pan <= 1))
+      throw new Error(`cue ${index}: pan must be -1..1`);
+    if (send !== undefined && !(typeof send === "number" && send >= 0 && send <= 1))
+      throw new Error(`cue ${index}: send must be 0..1`);
+    if (name !== undefined && typeof name !== "string")
+      throw new Error(`cue ${index}: name must be text`);
+    return {
+      t,
+      sfx,
+      gain,
+      pan,
+      ...(send === undefined ? {} : { send }),
+      ...(name ? { name: name.slice(0, 60) } : {}),
+    };
+  });
+}
+
+/**
+ * Validate the camera's speed curve as the kit writes it.
+ * @param {unknown} curve
+ * @returns {{ rate: number; start: number; values: number[] }}
+ */
+export function validateAir(curve) {
+  if (!curve || typeof curve !== "object") throw new Error("air must be an object");
+  const { rate, start, values } = /** @type {Record<string, unknown>} */ (curve);
+  if (!(typeof rate === "number" && rate >= 10 && rate <= 240))
+    throw new Error("air: rate must be 10..240");
+  if (!(typeof start === "number" && Number.isFinite(start) && start >= 0))
+    throw new Error("air: start must be a time >= 0");
+  if (!Array.isArray(values) || values.length > MAX_AIR_SAMPLES)
+    throw new Error(`air: values must be a list of at most ${MAX_AIR_SAMPLES} samples`);
+  if (!values.every((v) => typeof v === "number" && Number.isFinite(v) && v >= 0))
+    throw new Error("air: every value must be a speed >= 0");
+  return { rate, start, values };
+}
+
+/** Read a JSON attribute the kit wrote on the root <html> element, or null. */
+function readRootAttribute(dom, attribute, label) {
+  // Chrome escapes `&` and `"` in attribute values but not `<` or `>`, so skip
+  // over quoted values instead of stopping at the first `>`.
+  const tag = /<html\b(?:[^>"']|"[^"]*"|'[^']*')*>/i.exec(dom)?.[0] ?? "";
+  const match = new RegExp(`\\s${attribute}="([^"]*)"`).exec(tag);
+  if (!match) return null;
+  const json = (match[1] ?? "").replace(/&(quot|amp|lt|gt|apos|#39|#34);/g, (_, e) => ENTITIES[e]);
+  try {
+    return { value: JSON.parse(json) };
+  } catch {
+    throw new Error(`the page wrote an unreadable ${label}`);
+  }
+}
+
+/**
+ * The camera speed curve a loaded page wrote, or null without a kit camera.
+ * @param {string} dom serialized DOM
+ */
+export function readAir(dom) {
+  const found = readRootAttribute(dom, "data-ez-air", "camera curve");
+  return found ? validateAir(found.value) : null;
+}
+
+/**
+ * The cue list a loaded page wrote on its root element, or null when the
+ * composition marked none.
+ * @param {string} dom serialized DOM, as `chrome --dump-dom` prints it
+ */
+export function readCues(dom) {
+  const found = readRootAttribute(dom, "data-ez-cues", "cue list");
+  return found ? validateCues(found.value) : null;
+}
+
+/** Serve `root` read-only on 127.0.0.1; never outside it. */
+export async function serve(root) {
+  const base = await realpath(root);
+  const server = createServer(async (request, response) => {
+    try {
+      if (request.method !== "GET" && request.method !== "HEAD") {
+        response.writeHead(405).end();
+        return;
+      }
+      const path = decodeURIComponent(new URL(request.url ?? "/", "http://127.0.0.1").pathname);
+      const file = await realpath(resolve(base, `.${path}`));
+      const inside = relative(base, file);
+      if (inside.startsWith("..") || isAbsolute(inside) || !(await stat(file)).isFile()) {
+        response.writeHead(404).end();
+        return;
+      }
+      response.writeHead(200, {
+        "content-type": TYPES[extname(file).toLowerCase()] ?? "application/octet-stream",
+      });
+      if (request.method === "HEAD") response.end();
+      else createReadStream(file).pipe(response);
+    } catch {
+      response.writeHead(404).end();
+    }
+  });
+  await new Promise((resolveListen, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolveListen);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Could not start the page server");
+  return { server, port: address.port };
+}
+
+export async function chromePath() {
+  const override = process.env.EZ_MOTION_CHROME?.trim();
+  if (override) return resolve(override);
+  try {
+    const { stdout } = await run(
+      process.execPath,
+      [join(here, "hyperframes.mjs"), "browser", "path"],
+      {
+        timeout: 60_000,
+        windowsHide: true,
+      },
+    );
+    const found = stdout.trim().split(/\r?\n/).at(-1)?.trim();
+    if (found) return found;
+  } catch {
+    /* fall through to the instruction below */
+  }
+  throw new Error("Chrome for HyperFrames is missing; run `hf browser ensure` first");
+}
+
+/** The puppeteer-core HyperFrames itself drives Chrome with. */
+async function loadPuppeteer() {
+  const fromHere = createRequire(import.meta.url);
+  const fromHyperframes = createRequire(fromHere.resolve("hyperframes/package.json"));
+  const mod = await import(pathToFileURL(fromHyperframes.resolve("puppeteer-core")).href);
+  return mod.default ?? mod;
+}
+
+/** Load the page in headless Chrome and return its DOM after the script ran. */
+async function dumpDom(chrome, url, signal) {
+  const puppeteer = await loadPuppeteer();
+  const profile = await mkdtemp(join(tmpdir(), "ez-motion-cues-"));
+  let browser;
+  try {
+    browser = await puppeteer.launch({
+      executablePath: chrome,
+      headless: /chrome-headless-shell/i.test(basename(chrome)) ? "shell" : true,
+      userDataDir: profile,
+      // Linux CI containers often lack the user namespaces Chrome's sandbox needs.
+      args: [
+        "--disable-gpu",
+        "--mute-audio",
+        ...(process.platform === "linux" ? ["--no-sandbox"] : []),
+      ],
+      handleSIGINT: false,
+      handleSIGTERM: false,
+      handleSIGHUP: false,
+      timeout: 60_000,
+      signal,
+    });
+    const page = await browser.newPage();
+    page.setDefaultTimeout(60_000);
+    await page.goto(url, { waitUntil: "load" });
+    // Timelines may be built after fonts load (the documented async setup) and
+    // are registered last; the kit writes its cues in a microtask after that.
+    await page.evaluate(async () => {
+      await document.fonts.ready;
+    });
+    await page
+      .waitForFunction(() => Object.keys(window.__timelines ?? {}).length > 0, { timeout: 8000 })
+      .catch(() => undefined);
+    await page.evaluate(() => new Promise((done) => setTimeout(done, 0)));
+    const dom = await page.content();
+    if (!dom) throw new Error("empty page");
+    return dom.slice(0, MAX_DOM_BYTES);
+  } catch (error) {
+    if (signal?.aborted) throw new Error("cancelled");
+    throw new Error(
+      `Chrome could not load the page: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  } finally {
+    await browser?.close().catch(() => undefined);
+    await rm(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
+}
+
+function parseArgs(argv) {
+  const [project, ...rest] = argv;
+  if (!project || project.startsWith("--"))
+    throw new Error(
+      "usage: cues.mjs <project-dir> [--out <cues.json>] [--composition <file.html>]",
+    );
+  const options = { project: resolve(project), composition: "index.html", out: "" };
+  for (let index = 0; index < rest.length; index += 2) {
+    const flag = rest[index];
+    const value = rest[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`${flag} needs a value`);
+    if (flag === "--out") options.out = resolve(value);
+    else if (flag === "--composition") options.composition = value;
+    else throw new Error(`Unsupported option ${flag}`);
+  }
+  options.out ||= join(options.project, "cues.json");
+  return options;
+}
+
+async function main() {
+  const started = performance.now();
+  const options = parseArgs(process.argv.slice(2));
+  if (!(await stat(options.project).catch(() => null))?.isDirectory())
+    throw new Error("Expected a project folder");
+  const page = resolve(options.project, options.composition);
+  if (!page.startsWith(options.project + sep) || extname(page).toLowerCase() !== ".html")
+    throw new Error("--composition must be an .html file inside the project");
+  if (!(await stat(page).catch(() => null))?.isFile())
+    throw new Error(`${options.composition} not found`);
+  const chrome = await chromePath();
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGTERM", abort);
+  process.once("SIGINT", abort);
+  const { server, port } = await serve(options.project);
+  try {
+    const route = relative(options.project, page).split(sep).map(encodeURIComponent).join("/");
+    const dom = await dumpDom(chrome, `http://127.0.0.1:${port}/${route}`, controller.signal);
+    const cues = readCues(dom);
+    const air = readAir(dom);
+    // A plain page load does not mount sub-composition files, so their scripts never run.
+    const unloaded = (dom.match(/\sdata-composition-src=/g) ?? []).length;
+    const note = unloaded
+      ? `${unloaded} sub-composition file(s) were not loaded; cues marked inside them are missing. Mark cues in the root composition's script.`
+      : undefined;
+    if (!cues && !air)
+      throw new Error(
+        `The composition marked no cues. Load the kit and call kit.cue(tl, at, sfx) where each sound belongs.${note ? ` ${note}` : ""}`,
+      );
+    const file = {
+      version: CUES_VERSION,
+      composition: options.composition,
+      cues: cues ?? [],
+      ...(air ? { air } : {}),
+    };
+    await writeFile(options.out, `${JSON.stringify(file, null, 2)}\n`);
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        out: options.out,
+        cues: file.cues.length,
+        sounds: [...new Set(file.cues.map((cue) => cue.sfx))].sort(),
+        ...(air ? { cameraAir: true } : {}),
+        ...(note ? { note } : {}),
+        elapsedMs: Math.round(performance.now() - started),
+      })}\n`,
+    );
+  } finally {
+    process.removeListener("SIGTERM", abort);
+    process.removeListener("SIGINT", abort);
+    server.closeAllConnections();
+    server.close();
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    await main();
+  } catch (error) {
+    process.stderr.write(
+      `Cue export failed: ${error instanceof Error ? error.message : "invalid input"}\n`,
+    );
+    process.exitCode = 1;
+  }
+}

package/assets/motion/bin/library.mjs

@@ -8,11 +8,14 @@
 //   node library.mjs show <id>
 //   node library.mjs look <project-dir> <look-id>
 //   node library.mjs add <project-dir> <piece-id> [<piece-id> ...] [--force]
+//   node library.mjs kit <project-dir>
 //
 // `look` writes <project>/assets/looks/<id>.css (design tokens as CSS
 // variables) and installs the look's fonts. `add` copies pieces into
 // <project>/compositions/<id>.html, installs their fonts, and records
-// third-party credits in CREDITS.md. Every command prints one JSON line.
+// third-party credits in CREDITS.md. `kit` installs the move kit
+// (library/kit/moves.js) as <project>/assets/kit/moves.js; `add` does the
+// same for pieces that require it. Every command prints one JSON line.
 import { execFileSync } from "node:child_process";
 import { appendFile, copyFile, mkdir, readFile, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -49,15 +52,28 @@ async function projectDir(arg) {
 /** Returns the installed families and fonts.mjs's page-ready <style> block. */
 function installFonts(project, families) {
   if (families.length === 0) return { installed: [], head: [] };
-  const out = execFileSync(process.execPath, [join(BIN, "fonts.mjs"), "add", project, ...families], {
-    encoding: "utf8",
-  });
+  const out = execFileSync(
+    process.execPath,
+    [join(BIN, "fonts.mjs"), "add", project, ...families],
+    {
+      encoding: "utf8",
+    },
+  );
   const result = JSON.parse(out);
   if (!result.ok) fail(`Font install failed: ${result.error}`);
   // Inline, not a linked fonts.css: `hf check` only sees @font-face written in the page.
   return { installed: result.installed, head: [result.head] };
 }
 
+const KIT_HEAD = '<script src="assets/kit/moves.js"></script>';
+
+/** Copies the move kit into the project; returns the <script> for the root head. */
+async function installKit(project) {
+  await mkdir(join(project, "assets", "kit"), { recursive: true });
+  await copyFile(join(LIBRARY, "kit", "moves.js"), join(project, "assets", "kit", "moves.js"));
+  return KIT_HEAD;
+}
+
 const summary = (entry, type) => ({
   id: entry.id,
   type,
@@ -76,7 +92,8 @@ if (command === "list") {
   const which = rest[0] === "looks" || rest[0] === "pieces" ? rest[0] : undefined;
   const kindIndex = rest.indexOf("--kind");
   const kind = kindIndex >= 0 ? rest[kindIndex + 1] : undefined;
-  if (kind && !lib.kinds.includes(kind)) fail(`Unknown kind "${kind}". Kinds: ${lib.kinds.join(", ")}`);
+  if (kind && !lib.kinds.includes(kind))
+    fail(`Unknown kind "${kind}". Kinds: ${lib.kinds.join(", ")}`);
   const looks = which === "pieces" || kind ? [] : lib.looks.map((l) => summary(l, "look"));
   const pieces =
     which === "looks"
@@ -85,7 +102,8 @@ if (command === "list") {
   // Contact sheets show many previews in one image read.
   const sheets = {};
   if (looks.length > 0) sheets.looks = join(LIBRARY, "sheets", "looks.jpg");
-  for (const k of new Set(pieces.map((p) => p.kind))) sheets[k] = join(LIBRARY, "sheets", `${k}.jpg`);
+  for (const k of new Set(pieces.map((p) => p.kind)))
+    sheets[k] = join(LIBRARY, "sheets", `${k}.jpg`);
   done({ ok: true, kinds: lib.kinds, sheets, looks, pieces });
 }
 
@@ -120,7 +138,11 @@ if (command === "show") {
     ...(look ?? piece),
     preview: join(dir, "preview.jpg"),
     files: look
-      ? { spec: join(dir, "look.md"), tokens: join(dir, "tokens.css"), sample: join(dir, "sample.html") }
+      ? {
+          spec: join(dir, "look.md"),
+          tokens: join(dir, "tokens.css"),
+          sample: join(dir, "sample.html"),
+        }
       : { source: join(dir, "piece.html") },
   });
 }
@@ -145,6 +167,18 @@ if (command === "look") {
   });
 }
 
+if (command === "kit") {
+  const project = await projectDir(rest[0]);
+  const kit = await installKit(project);
+  done({
+    ok: true,
+    installed: join(project, "assets", "kit", "moves.js"),
+    kit,
+    use: "Put kit in the root index.html <head> after GSAP; scripts then use window.GGMotionKit.",
+    reference: join(LIBRARY, "README.md"),
+  });
+}
+
 if (command === "add") {
   const force = rest.includes("--force");
   const [projectArg, ...ids] = rest.filter((a) => a !== "--force");
@@ -187,17 +221,26 @@ if (command === "add") {
   let importmap;
   if (pieces.some((p) => (p.requires ?? []).includes("three"))) {
     const three = JSON.parse(
-      execFileSync(process.execPath, [join(BIN, "three.mjs"), "add", project], { encoding: "utf8" }),
+      execFileSync(process.execPath, [join(BIN, "three.mjs"), "add", project], {
+        encoding: "utf8",
+      }),
     );
     if (!three.ok) fail(`Three.js install failed: ${three.error}`);
     importmap = three.importmap;
   }
+  // Kit pieces call window.GGMotionKit, loaded once by the root page.
+  const kit = pieces.some((p) => (p.requires ?? []).includes("kit"))
+    ? await installKit(project)
+    : undefined;
   done({
     ok: true,
     added,
     kept,
     fonts: fonts.installed,
-    ...(importmap ? { importmap, note: "put importmap in index.html <head> before any module script" } : {}),
+    ...(importmap
+      ? { importmap, note: "put importmap in index.html <head> before any module script" }
+      : {}),
+    ...(kit ? { kit, kitNote: "put kit in index.html <head> after GSAP" } : {}),
     mount: pieces.map(
       (p) =>
         `<div id="${p.id}-clip" data-composition-id="${p.id}" data-composition-src="compositions/${p.id}.html" data-start="0" data-duration="${p.duration}" data-width="1920" data-height="1080" data-track-index="0"></div>`,
@@ -206,5 +249,5 @@ if (command === "add") {
 }
 
 fail(
-  "usage: library.mjs list [looks|pieces] [--kind k] | search <words> | show <id> | look <project> <look-id> | add <project> <piece-id>... [--force]",
+  "usage: library.mjs list [looks|pieces] [--kind k] | search <words> | show <id> | look <project> <look-id> | add <project> <piece-id>... [--force] | kit <project>",
 );