agent-nuvira 3.5.9 → 3.5.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +19 -1
  2. package/dist/cli/cli-program.d.ts.map +1 -1
  3. package/dist/cli/cli-program.js +6 -0
  4. package/dist/cli/cli-program.js.map +1 -1
  5. package/dist/cli/motion.d.ts +53 -0
  6. package/dist/cli/motion.d.ts.map +1 -0
  7. package/dist/cli/motion.js +516 -0
  8. package/dist/cli/motion.js.map +1 -0
  9. package/dist/learning/machine-facts.d.ts +7 -0
  10. package/dist/learning/machine-facts.d.ts.map +1 -1
  11. package/dist/learning/machine-facts.js +37 -2
  12. package/dist/learning/machine-facts.js.map +1 -1
  13. package/dist/skills/bundled-skills-phase3.d.ts.map +1 -1
  14. package/dist/skills/bundled-skills-phase3.js +3 -3
  15. package/dist/skills/bundled-skills-phase3.js.map +1 -1
  16. package/dist/skills/sandbox-executor.d.ts.map +1 -1
  17. package/dist/skills/sandbox-executor.js +115 -34
  18. package/dist/skills/sandbox-executor.js.map +1 -1
  19. package/dist/tools/modality/motion-tool.d.ts +28 -1
  20. package/dist/tools/modality/motion-tool.d.ts.map +1 -1
  21. package/dist/tools/modality/motion-tool.js +261 -10
  22. package/dist/tools/modality/motion-tool.js.map +1 -1
  23. package/dist/tools/modality/motion.d.ts +403 -3
  24. package/dist/tools/modality/motion.d.ts.map +1 -1
  25. package/dist/tools/modality/motion.js +1096 -41
  26. package/dist/tools/modality/motion.js.map +1 -1
  27. package/dist/tools/registry.d.ts.map +1 -1
  28. package/dist/tools/registry.js +34 -4
  29. package/dist/tools/registry.js.map +1 -1
  30. package/dist/web-dashboard/motion-data.d.ts +62 -0
  31. package/dist/web-dashboard/motion-data.d.ts.map +1 -0
  32. package/dist/web-dashboard/motion-data.js +91 -0
  33. package/dist/web-dashboard/motion-data.js.map +1 -0
  34. package/dist/web-dashboard/server.d.ts.map +1 -1
  35. package/dist/web-dashboard/server.js +58 -30
  36. package/dist/web-dashboard/server.js.map +1 -1
  37. package/dist/web-dashboard/src/types.d.ts +31 -0
  38. package/dist/web-dashboard/src/types.d.ts.map +1 -1
  39. package/package.json +1 -1
  40. package/src/web-dashboard/public/assets/{index-CzRU84ET.css → index-CXdBvA0N.css} +1 -1
  41. package/src/web-dashboard/public/assets/{index-CGYIlLpO.js → index-DfjkO16t.js} +81 -81
  42. package/src/web-dashboard/public/assets/{index-CGYIlLpO.js.map → index-DfjkO16t.js.map} +1 -1
  43. package/src/web-dashboard/public/index.html +2 -2
@@ -32,10 +32,11 @@
32
32
  * one is reported by name WITH the command that installs it, and never as a
33
33
  * half-written video file.
34
34
  */
35
- import { spawn } from 'node:child_process';
36
- import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
35
+ import { spawn, spawnSync } from 'node:child_process';
36
+ import { createHash } from 'node:crypto';
37
+ import { closeSync, copyFileSync, existsSync, linkSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync, } from 'node:fs';
37
38
  import { tmpdir } from 'node:os';
38
- import { basename, join } from 'node:path';
39
+ import { basename, extname, isAbsolute, join, resolve } from 'node:path';
39
40
  import { envBuff } from '../../config/paths.js';
40
41
  import { isBrowserAvailable } from './browser.js';
41
42
  import { artifactsDir, binaryOnPath, safeArtifactName } from './shared.js';
@@ -194,12 +195,741 @@ export const MOTION_READY_SCRIPT = `(() =>
194
195
  if (document.fonts && document.fonts.ready) document.fonts.ready.then(done, done);
195
196
  else done();
196
197
  }))()`;
198
+ // ─── Frame-sequence input (ANY renderer, not only a browser page) ───────────
199
+ //
200
+ // WHY THIS EXISTS. "The animation is code" was true of this module only for the
201
+ // code a BROWSER can run: a seekable HTML page. But the same technique is how
202
+ // people render motion with Manim, Blender, a headless Three.js scene, Remotion,
203
+ // matplotlib — and with a plain Python + PIL renderer, which is exactly how a
204
+ // live run on this product produced a 600-frame paper-craft commercial: the
205
+ // model wrote render.py, ran it, and then had to shell out to ffmpeg ITSELF.
206
+ // Everything the motion layer owns was bypassed: no render id, no history, no
207
+ // captions, no narration, no revision, no frame/duration reporting, and a failed
208
+ // encode left whatever ffmpeg left behind.
209
+ //
210
+ // So a frame sequence is now a first-class SOURCE. The caller's program renders
211
+ // frames; this module encodes them, reports their real count/size/duration, and
212
+ // keeps them in the same history as a browser render. It needs only ffmpeg —
213
+ // chromium is not involved, because nothing here has to be seeked.
214
+ /** The image types a frame sequence may use (ffmpeg's image2 decodes all four). */
215
+ const FRAME_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'];
216
+ /**
217
+ * Order frames the way a person numbers them: `f_2.png` before `f_10.png`.
218
+ *
219
+ * A plain lexicographic sort puts `f_10` before `f_2`, which reverses the video
220
+ * silently — the file still plays, so nothing downstream can catch it.
221
+ */
222
+ export function naturalFrameOrder(a, b) {
223
+ return a.localeCompare(b, 'en', { numeric: true, sensitivity: 'base' });
224
+ }
225
+ /**
226
+ * A tiny glob: `*` and `?` only, matched against the basename.
227
+ *
228
+ * Deliberately not a dependency. A caller that needs more than this is naming
229
+ * frames in a way they can name for ffmpeg directly.
230
+ */
231
+ function matchesGlob(name, glob) {
232
+ const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.');
233
+ return new RegExp(`^${escaped}$`, 'i').test(name);
234
+ }
235
+ /** True for a path that names an image in a format ffmpeg can decode here. */
236
+ function isFrameName(name) {
237
+ return FRAME_EXTENSIONS.includes(extname(name).toLowerCase());
238
+ }
239
+ /**
240
+ * A glob over a RELATIVE path, for a pattern that selects across subdirectories.
241
+ *
242
+ * `*` stays inside one path segment and `**` crosses segments, which is what both
243
+ * a glob and a person mean by them. Only used when the pattern actually contains a
244
+ * separator — otherwise the cheaper basename match applies.
245
+ */
246
+ function matchesFramePath(rel, glob) {
247
+ // Built in ONE pass. Chained `.replace()` calls corrupt this: replacing `?`
248
+ // afterwards rewrites the `?` inside the `(?:.*/)?` an earlier call inserted, and
249
+ // replacing `*` rewrites the `*` inside a `.*` — which turned `**/*.png` into a
250
+ // pattern that matched nothing at all.
251
+ let source = '';
252
+ for (let i = 0; i < glob.length; i += 1) {
253
+ const ch = glob[i];
254
+ if (ch === '*') {
255
+ if (glob[i + 1] === '*') {
256
+ // `**/` crosses segments and may match none of them, so `**/*.png` still
257
+ // finds frames at the top level as well as in subdirectories.
258
+ if (glob[i + 2] === '/') {
259
+ source += '(?:.*/)?';
260
+ i += 2;
261
+ }
262
+ else {
263
+ source += '.*';
264
+ i += 1;
265
+ }
266
+ }
267
+ else {
268
+ source += '[^/]*';
269
+ }
270
+ }
271
+ else if (ch === '?') {
272
+ source += '[^/]';
273
+ }
274
+ else {
275
+ source += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
276
+ }
277
+ }
278
+ return new RegExp(`^${source}$`, 'i').test(rel);
279
+ }
280
+ /** How deep a recursive frame scan descends (a render tree, not a filesystem walk). */
281
+ const FRAME_SCAN_DEPTH = 4;
282
+ const MISSING_NUMBERS_LISTED = 8;
283
+ /** `frame_0001` → `{ prefix: 'frame_', number: 1 }`; null when there is no number. */
284
+ function frameNumber(name) {
285
+ const stem = basename(name, extname(name));
286
+ const match = /^(.*?)(\d+)(\D*)$/.exec(stem);
287
+ if (!match)
288
+ return null;
289
+ return { prefix: `${match[1]}${match[3]}`, number: Number.parseInt(match[2], 10) };
290
+ }
291
+ /** One directory's entries, dotfiles excluded. Empty on any error (never throws). */
292
+ function listDir(dir) {
293
+ try {
294
+ return readdirSync(dir, { withFileTypes: true })
295
+ .filter((e) => !e.name.startsWith('.'))
296
+ .map((e) => ({ name: e.name, isDir: e.isDirectory() }));
297
+ }
298
+ catch {
299
+ return [];
300
+ }
301
+ }
302
+ /**
303
+ * Measure a frame directory BEFORE encoding it.
304
+ *
305
+ * The render path used to take the file list on trust, which is fine for a clean
306
+ * `f_0001.png … f_0600.png` and wrong for everything else: two interleaved
307
+ * sequences concatenate into one video, a numbering gap shortens it, and a nested
308
+ * layout finds nothing at all. Every one of those produces a file that plays, so
309
+ * nothing downstream can catch it — the scan is what turns them into a warning or
310
+ * a refusal at the moment the facts are still available.
311
+ */
312
+ export function scanFrameDirectory(dir, pattern) {
313
+ const wanted = typeof pattern === 'string' && pattern.trim() ? pattern.trim() : undefined;
314
+ const recursing = Boolean(wanted && /[/\\]/.test(wanted));
315
+ /** Absolute path + the path RELATIVE to `dir`, which is what play order sorts on. */
316
+ const found = [];
317
+ let excludedByPattern = 0;
318
+ const walk = (base, relBase, depth) => {
319
+ for (const entry of listDir(base)) {
320
+ const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
321
+ if (entry.isDir) {
322
+ if (recursing && depth < FRAME_SCAN_DEPTH)
323
+ walk(join(base, entry.name), rel, depth + 1);
324
+ continue;
325
+ }
326
+ if (!isFrameName(entry.name))
327
+ continue;
328
+ const matches = recursing
329
+ ? matchesFramePath(rel, wanted)
330
+ : !wanted || matchesGlob(entry.name, wanted);
331
+ if (matches)
332
+ found.push({ abs: join(base, entry.name), rel });
333
+ else
334
+ excludedByPattern += 1;
335
+ }
336
+ };
337
+ walk(dir, '', 0);
338
+ // Sorted on the RELATIVE path, so a recursive scan plays in tree order rather
339
+ // than in whatever order readdir happened to return.
340
+ const sorted = [...found].sort((a, b) => naturalFrameOrder(a.rel, b.rel));
341
+ const files = sorted.map((f) => f.abs);
342
+ // Subdirectories holding frames, for the common case where someone points at a
343
+ // parent directory: without this the only report is "no frames found", which
344
+ // sends them looking in the wrong place.
345
+ const nested = [];
346
+ if (!recursing) {
347
+ for (const entry of listDir(dir)) {
348
+ if (!entry.isDir)
349
+ continue;
350
+ const count = collectFrameFiles(join(dir, entry.name), undefined, true).length;
351
+ if (count > 0)
352
+ nested.push({ dir: entry.name, frames: count });
353
+ }
354
+ }
355
+ const byPrefix = new Map();
356
+ let unnumbered = 0;
357
+ const extensions = new Set();
358
+ for (const file of files) {
359
+ extensions.add(extname(file).toLowerCase());
360
+ const parsed = frameNumber(file);
361
+ if (!parsed) {
362
+ unnumbered += 1;
363
+ continue;
364
+ }
365
+ const numbers = byPrefix.get(parsed.prefix) ?? [];
366
+ numbers.push(parsed.number);
367
+ byPrefix.set(parsed.prefix, numbers);
368
+ }
369
+ let dominantPrefix = null;
370
+ let dominantCount = 0;
371
+ for (const [prefix, numbers] of byPrefix) {
372
+ if (numbers.length > dominantCount) {
373
+ dominantPrefix = prefix;
374
+ dominantCount = numbers.length;
375
+ }
376
+ }
377
+ const missing = [];
378
+ let missingTotal = 0;
379
+ if (dominantPrefix) {
380
+ const numbers = byPrefix.get(dominantPrefix);
381
+ const present = new Set(numbers);
382
+ const min = Math.min(...numbers);
383
+ const max = Math.max(...numbers);
384
+ // Only a sequence that CLAIMS a dense range is measured: 600 frames numbered
385
+ // 1..600 with one absent is a dropped frame, whereas five frames numbered
386
+ // 100,200,300,400,500 is a naming scheme, not five gaps.
387
+ if (max - min + 1 <= numbers.length * 2) {
388
+ for (let n = min; n <= max; n += 1) {
389
+ if (present.has(n))
390
+ continue;
391
+ missingTotal += 1;
392
+ if (missing.length < MISSING_NUMBERS_LISTED)
393
+ missing.push(n);
394
+ }
395
+ }
396
+ }
397
+ return {
398
+ files,
399
+ prefixes: [...byPrefix.keys()].sort((a, b) => (byPrefix.get(b).length - byPrefix.get(a).length) || a.localeCompare(b)),
400
+ extensions: [...extensions].sort(),
401
+ unnumbered,
402
+ missing,
403
+ missingTotal,
404
+ dominantPrefix,
405
+ nested: nested.sort((a, b) => b.frames - a.frames),
406
+ excludedByPattern,
407
+ };
408
+ }
409
+ /**
410
+ * Every image frame in `dir`, in play order.
411
+ *
412
+ * `pattern` is an optional glob — over the basename (`f_*.png`) for a directory
413
+ * that holds more than one sequence, or over a relative path (`**\/f_*.png`) when
414
+ * the frames sit in subdirectories. An empty result is a REFUSAL, not a render of
415
+ * nothing: use {@link frameScanHint} to say where the frames actually are.
416
+ */
417
+ export function collectFrameFiles(dir, pattern, bypassScan = false) {
418
+ if (bypassScan) {
419
+ // Used by the scan's own nested probe, which needs a plain listing of a
420
+ // subdirectory without re-entering the scan that calls it.
421
+ let entries = [];
422
+ try {
423
+ entries = readdirSync(dir);
424
+ }
425
+ catch {
426
+ return [];
427
+ }
428
+ return entries
429
+ .filter((name) => !name.startsWith('.'))
430
+ .filter((name) => isFrameName(name))
431
+ .filter((name) => !pattern || matchesGlob(name, pattern))
432
+ .sort(naturalFrameOrder)
433
+ .map((name) => join(dir, name));
434
+ }
435
+ return scanFrameDirectory(dir, pattern).files;
436
+ }
437
+ /**
438
+ * What the render says when a frame directory came back EMPTY.
439
+ *
440
+ * Names the extensions that were looked for and any subdirectory that holds
441
+ * frames, because "no image frames found" without those two facts is a dead end.
442
+ */
443
+ export function frameScanHint(dir, pattern) {
444
+ const scan = scanFrameDirectory(dir, pattern);
445
+ const parts = [
446
+ `no image frames found in ${dir}${pattern ? ` matching '${pattern}'` : ''}.`,
447
+ `Looked for ${FRAME_EXTENSIONS.join(', ')}.`,
448
+ ];
449
+ if (scan.nested.length > 0) {
450
+ const where = scan.nested.slice(0, 4).map((n) => `${n.dir}/ (${n.frames} frames)`).join(', ');
451
+ parts.push(`The frames are one level down: ${where} — point frames_dir there, or pass frames_pattern '**/*.png'.`);
452
+ }
453
+ if (scan.excludedByPattern > 0) {
454
+ parts.push(`${scan.excludedByPattern} image file(s) in it did not match the pattern.`);
455
+ }
456
+ return parts.join(' ');
457
+ }
458
+ /**
459
+ * What the render must SAY about a scanned directory, before it encodes.
460
+ *
461
+ * Each warning is a specific way the video is about to be wrong while still
462
+ * playing: several sequences concatenated, a numbering gap that shortens it, mixed
463
+ * formats decoded as one, frames in subdirectories silently skipped.
464
+ */
465
+ export function frameScanWarnings(scan) {
466
+ const warnings = [];
467
+ if (scan.prefixes.length > 1) {
468
+ const named = scan.prefixes.slice(0, 4).map((p) => `'${p}'`).join(', ');
469
+ warnings.push(`${scan.prefixes.length} different frame sequences are in this directory (${named}) and they were concatenated in that order — ` +
470
+ 'if that is not what you meant, pass frames_pattern to pick one');
471
+ }
472
+ if (scan.extensions.length > 1) {
473
+ warnings.push(`the frames mix ${scan.extensions.join(' and ')} — every frame is decoded as the first one's format, so a mixed set can fail to decode`);
474
+ }
475
+ if (scan.missingTotal > 0) {
476
+ const shown = scan.missing.slice(0, MISSING_NUMBERS_LISTED).join(', ');
477
+ warnings.push(`${scan.missingTotal} frame number(s) are missing from the '${scan.dominantPrefix}' sequence (${shown}${scan.missingTotal > scan.missing.length ? ', …' : ''}) — ` +
478
+ 'the video is shorter than the timeline that produced it');
479
+ }
480
+ if (scan.unnumbered > 0) {
481
+ warnings.push(`${scan.unnumbered} frame(s) carry no number in their name, so they are ordered alphabetically rather than by a timeline`);
482
+ }
483
+ if (scan.nested.length > 0) {
484
+ const where = scan.nested.slice(0, 4).map((n) => `${n.dir}/ (${n.frames})`).join(', ');
485
+ warnings.push(`frames in subdirectories were IGNORED by this scan: ${where} — pass frames_pattern '**/*.png' to include them`);
486
+ }
487
+ return warnings;
488
+ }
489
+ /**
490
+ * Pixel size straight from the file header — no image library, no decode.
491
+ *
492
+ * Read because the size is a FACT the render must report and the ffmpeg encode
493
+ * needs consistent dimensions: a sequence that changes size mid-flight produces
494
+ * a file with a broken middle, and the only honest thing to do is say so.
495
+ * Returns null for a format this does not parse (a caller's exotic frame type),
496
+ * and the caller then reports the size as unknown rather than inventing one.
497
+ */
498
+ export function imageDimensions(file) {
499
+ let head;
500
+ try {
501
+ head = readFileSync(file).subarray(0, 65_536);
502
+ }
503
+ catch {
504
+ return null;
505
+ }
506
+ // PNG: 8-byte signature, then IHDR with width/height as big-endian uint32s.
507
+ if (head.length > 24 && head.toString('ascii', 1, 4) === 'PNG') {
508
+ return { width: head.readUInt32BE(16), height: head.readUInt32BE(20) };
509
+ }
510
+ // GIF: logical screen descriptor, little-endian uint16s.
511
+ if (head.length > 10 && head.toString('ascii', 0, 3) === 'GIF') {
512
+ return { width: head.readUInt16LE(6), height: head.readUInt16LE(8) };
513
+ }
514
+ // JPEG: walk the marker segments to a Start-Of-Frame, which carries the size.
515
+ if (head.length > 4 && head[0] === 0xff && head[1] === 0xd8) {
516
+ let offset = 2;
517
+ while (offset + 9 < head.length) {
518
+ if (head[offset] !== 0xff) {
519
+ offset += 1;
520
+ continue;
521
+ }
522
+ const marker = head[offset + 1];
523
+ // SOF0-SOF3, SOF5-SOF7, SOF9-SOF11, SOF13-SOF15 hold the frame size.
524
+ const isSof = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
525
+ if (isSof) {
526
+ return { width: head.readUInt16BE(offset + 7), height: head.readUInt16BE(offset + 5) };
527
+ }
528
+ const length = head.readUInt16BE(offset + 2);
529
+ if (length < 2)
530
+ return null;
531
+ offset += 2 + length;
532
+ }
533
+ }
534
+ return null;
535
+ }
536
+ /**
537
+ * Measure a frame directory: order, count, size, and how many frames disagree.
538
+ *
539
+ * `null` means there were no frames to measure (the caller refuses).
540
+ */
541
+ export function measureFrameSequence(files) {
542
+ if (files.length === 0)
543
+ return null;
544
+ const first = files[0];
545
+ const ext = extname(first).toLowerCase();
546
+ const size = imageDimensions(first);
547
+ let mismatched = 0;
548
+ if (size) {
549
+ for (const file of files.slice(1)) {
550
+ const other = imageDimensions(file);
551
+ if (other && (other.width !== size.width || other.height !== size.height))
552
+ mismatched += 1;
553
+ }
554
+ }
555
+ return {
556
+ files,
557
+ ext,
558
+ width: size?.width ?? 0,
559
+ height: size?.height ?? 0,
560
+ mismatched,
561
+ };
562
+ }
563
+ /**
564
+ * Give the caller's frames ffmpeg's expected names, inside the work dir.
565
+ *
566
+ * A LINK rather than a copy where the filesystem allows it: a 600-frame 720p
567
+ * sequence is hundreds of megabytes, and copying every frame to re-encode it
568
+ * would make this path slower than the browser one for no reason. Symlink, then
569
+ * hard link, then a real copy — the third only on a filesystem (or a Windows
570
+ * setup without the privilege) that refuses the first two.
571
+ */
572
+ export function linkFramesInto(files, workDir) {
573
+ const ext = extname(files[0] ?? 'f.png').toLowerCase();
574
+ files.forEach((file, index) => {
575
+ const target = join(workDir, `frame-${String(index + 1).padStart(5, '0')}${ext}`);
576
+ try {
577
+ symlinkSync(file, target);
578
+ return;
579
+ }
580
+ catch {
581
+ /* fall through: not every filesystem allows a symlink */
582
+ }
583
+ try {
584
+ linkSync(file, target);
585
+ return;
586
+ }
587
+ catch {
588
+ /* fall through: a different device, or no permission */
589
+ }
590
+ copyFileSync(file, target);
591
+ });
592
+ return join(workDir, `frame-%05d${ext}`);
593
+ }
594
+ // ─── The caller's renderer, recorded (what makes a frames revision a revision) ──
595
+ //
596
+ // A frames render cannot be revised from the manifest alone: this module never
597
+ // held the animation, only the images. So the caller may RECORD the command that
598
+ // produced them, and a later `revise` runs that command again to get FRESH frames
599
+ // before encoding. The alternative — re-encoding whatever is in the directory — is
600
+ // worse than useless: it returns a byte-identical file and calls it a revision.
601
+ /** How many existing files named by the command are recorded. */
602
+ const RECIPE_FILE_LIMIT = 24;
603
+ /** How many runs of a renderer are kept in the manifest as an audit trail. */
604
+ const RECIPE_RUN_LIMIT = 20;
605
+ /**
606
+ * sha256 of a file's contents, streamed in 1 MiB chunks.
607
+ *
608
+ * Chunked rather than `readFileSync` because the old code REFUSED to hash anything
609
+ * over 8 MiB and compared sizes instead — so editing a large CSV (the renderer's
610
+ * actual input) left the fingerprint unchanged, and the tool reported "the renderer
611
+ * did not change" about a file that had.
612
+ */
613
+ export function hashFile(file) {
614
+ let fd;
615
+ try {
616
+ if (!statSync(file).isFile())
617
+ return null;
618
+ fd = openSync(file, 'r');
619
+ }
620
+ catch {
621
+ return null;
622
+ }
623
+ try {
624
+ const hash = createHash('sha256');
625
+ const buffer = Buffer.alloc(1 << 20);
626
+ let position = 0;
627
+ for (;;) {
628
+ const read = readSync(fd, buffer, 0, buffer.length, position);
629
+ if (read <= 0)
630
+ break;
631
+ hash.update(buffer.subarray(0, read));
632
+ position += read;
633
+ }
634
+ return hash.digest('hex');
635
+ }
636
+ catch {
637
+ return null;
638
+ }
639
+ finally {
640
+ try {
641
+ closeSync(fd);
642
+ }
643
+ catch {
644
+ /* best-effort */
645
+ }
646
+ }
647
+ }
648
+ /**
649
+ * Record a renderer command: verbatim, plus a fingerprint of every file it names
650
+ * that exists right now.
651
+ *
652
+ * The token scan is deliberately literal — it records what the command POINTS AT,
653
+ * not an interpretation of it. A token that is not a file (a flag, a number, a
654
+ * subcommand) is skipped, so the fingerprint covers the script and its inputs and
655
+ * nothing invented.
656
+ */
657
+ export function captureRendererRecipe(command, cwd) {
658
+ const files = [];
659
+ const seen = new Set();
660
+ const tokens = command
661
+ .split(/\s+/)
662
+ .map((t) => t.replace(/^['"]|['"]$/g, ''))
663
+ .filter((t) => t && !t.startsWith('-'));
664
+ for (const token of tokens) {
665
+ if (files.length >= RECIPE_FILE_LIMIT)
666
+ break;
667
+ if (/^[\d.=]+$/.test(token))
668
+ continue;
669
+ const path = isAbsolute(token) ? token : resolve(cwd, token);
670
+ if (seen.has(path) || !existsSync(path))
671
+ continue;
672
+ let size = 0;
673
+ try {
674
+ const stat = statSync(path);
675
+ if (!stat.isFile())
676
+ continue;
677
+ size = stat.size;
678
+ }
679
+ catch {
680
+ continue;
681
+ }
682
+ seen.add(path);
683
+ files.push({ path, sha256: hashFile(path), size });
684
+ }
685
+ return { command, cwd, files, capturedAt: Date.now() };
686
+ }
687
+ /**
688
+ * Split a command into argv — respecting quotes, as a shell would.
689
+ *
690
+ * Only used when the command needs no shell (see {@link parseRendererCommand}), so
691
+ * this is what lets a plain `python render.py --frames 20` run WITHOUT one.
692
+ */
693
+ function splitArgv(command) {
694
+ const argv = [];
695
+ let current = '';
696
+ let quote = null;
697
+ let started = false;
698
+ const push = () => {
699
+ if (started)
700
+ argv.push(current);
701
+ current = '';
702
+ started = false;
703
+ };
704
+ for (const ch of command) {
705
+ if (quote) {
706
+ if (ch === quote)
707
+ quote = null;
708
+ else
709
+ current += ch;
710
+ continue;
711
+ }
712
+ if (ch === '"' || ch === "'") {
713
+ quote = ch;
714
+ started = true;
715
+ continue;
716
+ }
717
+ if (/\s/.test(ch)) {
718
+ push();
719
+ continue;
720
+ }
721
+ current += ch;
722
+ started = true;
723
+ }
724
+ push();
725
+ return argv;
726
+ }
727
+ /** Characters that only MEAN something to a shell: pipes, redirects, chaining, subshells, globs. */
728
+ const SHELL_SYNTAX = /[|&;<>()`$\\*?[\]{}~!\n]/;
729
+ /**
730
+ * Decide how to run a recorded command, preferring NOT to involve a shell at all.
731
+ *
732
+ * A recorded renderer is code the user already chose to run, but `shell: true` made
733
+ * every stored command a shell program: `$(...)`, backticks, `;` and redirects all
734
+ * became available to a string that only ever needed to be an argv. Splitting first
735
+ * means the common case (`python render.py --frames 20`) cannot be re-interpreted,
736
+ * and a command that genuinely needs a shell is marked so it can be reported.
737
+ */
738
+ export function parseRendererCommand(command) {
739
+ if (SHELL_SYNTAX.test(command))
740
+ return { argv: [command], viaShell: true };
741
+ const argv = splitArgv(command);
742
+ if (argv.length === 0)
743
+ return { argv: [command], viaShell: true };
744
+ return { argv, viaShell: false };
745
+ }
746
+ /** What a frame directory currently holds — cheap, and enough to spot a no-op run. */
747
+ export function frameSetFingerprint(dir, pattern) {
748
+ const files = collectFrameFiles(dir, pattern);
749
+ let bytes = 0;
750
+ let newestMtime = 0;
751
+ for (const file of files) {
752
+ try {
753
+ const stat = statSync(file);
754
+ bytes += stat.size;
755
+ newestMtime = Math.max(newestMtime, stat.mtimeMs);
756
+ }
757
+ catch {
758
+ /* a frame that vanished between listing and stat is not fatal here */
759
+ }
760
+ }
761
+ return { frames: files.length, bytes, newestMtime };
762
+ }
763
+ /**
764
+ * Whether the renderer still is what it was when the render was made.
765
+ *
766
+ * A changed script means the new frames are a DIFFERENT animation, and calling
767
+ * that a revision of the old one is the same lie as re-encoding stale frames — so
768
+ * the difference is reported by name and the caller decides.
769
+ */
770
+ export function verifyRendererRecipe(recipe) {
771
+ const changed = [];
772
+ for (const entry of recipe.files) {
773
+ let size;
774
+ try {
775
+ const stat = statSync(entry.path);
776
+ if (!stat.isFile()) {
777
+ changed.push(`${entry.path} is no longer a file`);
778
+ continue;
779
+ }
780
+ size = stat.size;
781
+ }
782
+ catch {
783
+ changed.push(`${entry.path} is gone`);
784
+ continue;
785
+ }
786
+ if (entry.sha256) {
787
+ if (hashFile(entry.path) !== entry.sha256)
788
+ changed.push(`${entry.path} changed`);
789
+ }
790
+ else if (size !== entry.size) {
791
+ changed.push(`${entry.path} changed size`);
792
+ }
793
+ }
794
+ return changed.length === 0 ? { ok: true } : { ok: false, changed };
795
+ }
796
+ /** How long a recorded renderer may run before it is killed. */
797
+ export const RENDERER_TIMEOUT = { defaultMs: 600_000, maxMs: 1_800_000 };
798
+ let _renderer = null;
799
+ /** Test seam: replace the renderer execution (so no test spawns python). */
800
+ export function setRendererRunnerForTests(runner) {
801
+ _renderer = runner;
802
+ }
803
+ /**
804
+ * Run the recorded command in the directory it was recorded in.
805
+ *
806
+ * This executes the caller's own program, which is the point of a frames
807
+ * revision — and it is why the recipe is only ever RECORDED from an explicit
808
+ * argument, never inferred from a directory listing: the only command that can run
809
+ * later is one a caller deliberately handed over.
810
+ */
811
+ export async function runRendererRecipe(recipe, timeoutMs = RENDERER_TIMEOUT.defaultMs) {
812
+ if (_renderer)
813
+ return _renderer(recipe, timeoutMs);
814
+ const budget = Math.min(Math.max(1_000, Math.round(timeoutMs)), RENDERER_TIMEOUT.maxMs);
815
+ const { argv, viaShell } = parseRendererCommand(recipe.command);
816
+ const startedAt = Date.now();
817
+ return new Promise((resolve) => {
818
+ let output = '';
819
+ let timedOut = false;
820
+ const child = spawn(argv[0], argv.slice(1), {
821
+ cwd: recipe.cwd,
822
+ // No shell for a command that is just an argv: nothing in it can then be
823
+ // re-interpreted as a subshell, a redirect or a chain.
824
+ shell: viaShell,
825
+ stdio: ['ignore', 'pipe', 'pipe'],
826
+ });
827
+ const append = (chunk) => {
828
+ if (output.length < 4_000)
829
+ output += chunk.toString('utf-8');
830
+ };
831
+ child.stdout?.on('data', append);
832
+ child.stderr?.on('data', append);
833
+ const timer = setTimeout(() => {
834
+ timedOut = true;
835
+ child.kill('SIGKILL');
836
+ }, budget);
837
+ const finish = (code, extra) => {
838
+ clearTimeout(timer);
839
+ resolve({
840
+ ok: code === 0,
841
+ code,
842
+ output: extra ? `${output}${extra}` : output,
843
+ timedOut,
844
+ viaShell,
845
+ ms: Date.now() - startedAt,
846
+ });
847
+ };
848
+ child.on('error', (err) => finish(-1, String(err)));
849
+ child.on('close', (code) => finish(code ?? -1));
850
+ });
851
+ }
852
+ /** Append a run to the audit trail, newest last and bounded. */
853
+ export function recordRendererRun(recipe, run, output) {
854
+ const record = {
855
+ at: Date.now(),
856
+ code: run.code,
857
+ ms: run.ms,
858
+ viaShell: run.viaShell,
859
+ frames: output.frames,
860
+ };
861
+ return { ...recipe, runs: [...(recipe.runs ?? []), record].slice(-RECIPE_RUN_LIMIT), output };
862
+ }
863
+ /**
864
+ * What a revision WOULD do, without doing any of it.
865
+ *
866
+ * The single most useful safety affordance here: a frames revision runs a stored
867
+ * command, and the caller deserves to see that command, where it runs, whether it
868
+ * needs a shell and which files it is about to touch — BEFORE it runs.
869
+ */
870
+ export function previewRendererRevision(recipe, framesDir, pattern) {
871
+ const { argv, viaShell } = parseRendererCommand(recipe.command);
872
+ const lines = [
873
+ `would run: ${recipe.command}`,
874
+ `in: ${recipe.cwd}`,
875
+ viaShell
876
+ ? 'through a SHELL (the command uses pipes/redirects/globs, so it is interpreted, not just executed)'
877
+ : `as argv: ${argv.map((a) => (a.includes(' ') ? `'${a}'` : a)).join(' ')} (no shell)`,
878
+ `frames: ${framesDir}${pattern ? ` matching '${pattern}'` : ''}`,
879
+ ];
880
+ if (recipe.files.length > 0) {
881
+ lines.push(`tracks ${recipe.files.length} file(s): ${recipe.files.map((f) => f.path).join(', ')}`);
882
+ }
883
+ else {
884
+ lines.push('tracks no files — the command names none that exist, so a change to its inputs cannot be detected');
885
+ }
886
+ const verify = verifyRendererRecipe(recipe);
887
+ lines.push(verify.ok ? 'its tracked files are unchanged' : `its tracked files CHANGED: ${verify.changed.join('; ')}`);
888
+ if (recipe.runs && recipe.runs.length > 0) {
889
+ const last = recipe.runs[recipe.runs.length - 1];
890
+ lines.push(`last ran ${new Date(last.at).toISOString()} (exit ${last.code}, ${last.ms}ms, ${last.frames} frames)`);
891
+ }
892
+ return lines;
893
+ }
894
+ /** One line naming a recorded renderer, for the history and for a refusal. */
895
+ export function describeRendererRecipe(recipe) {
896
+ return `${recipe.command} (in ${recipe.cwd})`;
897
+ }
898
+ /**
899
+ * What a FRAMES render needs: ffmpeg, and nothing else.
900
+ *
901
+ * Kept separate from {@link motionAvailability} on purpose. The browser report
902
+ * answers "can this machine render a page?", which is the wrong question when
903
+ * the caller brings its own frames — telling someone with 600 PNGs on disk that
904
+ * playwright is missing would refuse a render that is ready to run.
905
+ */
906
+ export function framesAvailability() {
907
+ if (_framesAvailabilityOverride)
908
+ return _framesAvailabilityOverride;
909
+ if (ffmpegAvailable())
910
+ return { ok: true, missing: [], hint: '' };
911
+ return {
912
+ ok: false,
913
+ missing: ['ffmpeg'],
914
+ hint: FFMPEG_INSTALL[process.platform] ?? FFMPEG_INSTALL.linux,
915
+ };
916
+ }
917
+ let _framesAvailabilityOverride = null;
918
+ /** Test seam: pin the frames-path availability (no ffmpeg needed to test). */
919
+ export function setFramesAvailabilityForTests(availability) {
920
+ _framesAvailabilityOverride = availability;
921
+ }
197
922
  /**
198
923
  * The ffmpeg argv for a frame sequence → video.
199
924
  *
200
- * `-start_number 1` because the capture numbers frames from 1 (`frame-00001.png`),
925
+ * `-start_number 1` because both frame sources number from 1 (`frame-00001.png`
926
+ * from the browser capture, and the links made by {@link linkFramesInto}),
201
927
  * `yuv420p` and even dimensions because that is what players actually play, and
202
928
  * `+faststart` so an mp4 can be streamed/previewed without a full download.
929
+ *
930
+ * `audioPath` is how a MUSIC or SFX bed is attached: an audio file the caller
931
+ already has is muxed at encode time, which is the same argv slot narration uses
932
+ * once it has been synthesized to a file.
203
933
  */
204
934
  export function buildFfmpegArgs(o) {
205
935
  const crf = clampInt(o.crf, 0, 51, o.format === 'gif' ? 0 : 20);
@@ -295,7 +1025,7 @@ export function motionAvailability() {
295
1025
  missing.push('chromium (playwright)');
296
1026
  hints.push('npm install -D playwright && npx playwright install chromium');
297
1027
  }
298
- if (!binaryOnPath('ffmpeg')) {
1028
+ if (!ffmpegAvailable()) {
299
1029
  missing.push('ffmpeg');
300
1030
  hints.push(FFMPEG_INSTALL[process.platform] ?? FFMPEG_INSTALL.linux);
301
1031
  }
@@ -316,11 +1046,92 @@ let _ffmpeg = null;
316
1046
  export function setFfmpegRunnerForTests(runner) {
317
1047
  _ffmpeg = runner;
318
1048
  }
319
- function runFfmpeg(args) {
1049
+ /**
1050
+ * Whether an ffmpeg is reachable at all — PATH, or one of the full kegs.
1051
+ *
1052
+ * A machine with only `ffmpeg-full` installed has a working renderer, so reporting
1053
+ * "missing ffmpeg" there would refuse a render that is ready to run.
1054
+ */
1055
+ function ffmpegAvailable() {
1056
+ return Boolean(envBuff('FFMPEG')) || binaryOnPath('ffmpeg') || FFMPEG_KEGS.some((keg) => existsSync(keg));
1057
+ }
1058
+ /**
1059
+ * The `ffmpeg-full` kegs, checked before PATH for one capability only: burning
1060
+ * captions.
1061
+ *
1062
+ * MEASURED 2026-10-17 on this machine: Homebrew's `ffmpeg` formula (9.0.2) is
1063
+ * built WITHOUT libass, so `subtitles=…` fails with "No such filter", while
1064
+ * `ffmpeg-full` (same version, already installed at /opt/homebrew/opt/ffmpeg-full)
1065
+ * has it. Telling the user to install ffmpeg-full is the correct advice — and
1066
+ * useless to someone who has it and does not know their PATH points elsewhere. So
1067
+ * the burn looks for itself.
1068
+ */
1069
+ const FFMPEG_KEGS = ['/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg', '/usr/local/opt/ffmpeg-full/bin/ffmpeg'];
1070
+ const _subtitlesSupport = new Map();
1071
+ let _subtitlesProbe = null;
1072
+ /** Test seam: decide subtitle support without probing real binaries. */
1073
+ export function setSubtitlesProbeForTests(probe) {
1074
+ _subtitlesProbe = probe;
1075
+ _subtitlesSupport.clear();
1076
+ }
1077
+ /** Whether a binary can burn subtitles (it lists the `subtitles` filter). Memoized. */
1078
+ export function supportsSubtitles(binary) {
1079
+ if (_subtitlesProbe)
1080
+ return _subtitlesProbe(binary);
1081
+ const cached = _subtitlesSupport.get(binary);
1082
+ if (cached !== undefined)
1083
+ return cached;
1084
+ if (binary !== 'ffmpeg' && !existsSync(binary)) {
1085
+ _subtitlesSupport.set(binary, false);
1086
+ return false;
1087
+ }
1088
+ let ok = false;
1089
+ try {
1090
+ const res = spawnSync(binary, ['-hide_banner', '-filters'], { encoding: 'utf-8' });
1091
+ ok = /^ .. (subtitles|ass) +V->V/m.test(`${res.stdout ?? ''}${res.stderr ?? ''}`);
1092
+ }
1093
+ catch {
1094
+ ok = false;
1095
+ }
1096
+ _subtitlesSupport.set(binary, ok);
1097
+ return ok;
1098
+ }
1099
+ /**
1100
+ * The ffmpeg to run: the explicit override, then PATH, then a full keg.
1101
+ *
1102
+ * PATH wins over the kegs so an installed ffmpeg keeps being the one used — a
1103
+ * machine with only `ffmpeg-full` still renders instead of reporting ffmpeg missing.
1104
+ */
1105
+ export function ffmpegBinary() {
1106
+ const override = envBuff('FFMPEG');
1107
+ if (override)
1108
+ return override;
1109
+ if (binaryOnPath('ffmpeg'))
1110
+ return 'ffmpeg';
1111
+ for (const keg of FFMPEG_KEGS)
1112
+ if (existsSync(keg))
1113
+ return keg;
1114
+ return 'ffmpeg';
1115
+ }
1116
+ /**
1117
+ * An ffmpeg that can burn captions, or null when this machine has none.
1118
+ *
1119
+ * Null is worth returning rather than falling back: a burn through a build without
1120
+ * libass fails after the encode, and the `.srt` is the part that still works.
1121
+ */
1122
+ export function ffmpegWithSubtitles() {
1123
+ const override = envBuff('FFMPEG');
1124
+ const candidates = override ? [override] : [...FFMPEG_KEGS, 'ffmpeg'];
1125
+ for (const binary of candidates)
1126
+ if (supportsSubtitles(binary))
1127
+ return binary;
1128
+ return null;
1129
+ }
1130
+ function runFfmpeg(args, binary) {
320
1131
  if (_ffmpeg)
321
- return _ffmpeg(args);
1132
+ return _ffmpeg(args, binary);
322
1133
  return new Promise((resolve) => {
323
- const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
1134
+ const child = spawn(binary ?? ffmpegBinary(), args, { stdio: ['ignore', 'ignore', 'pipe'] });
324
1135
  let stderr = '';
325
1136
  child.stderr?.on('data', (d) => {
326
1137
  if (stderr.length < 4_000)
@@ -339,15 +1150,32 @@ function runFfmpeg(args) {
339
1150
  * is muxed onto the finished video by stream copy.
340
1151
  */
341
1152
  export async function renderMotion(req) {
342
- const availability = motionAvailability();
1153
+ const framesDir = typeof req.framesDir === 'string' && req.framesDir.trim() ? req.framesDir.trim() : undefined;
1154
+ const scan = framesDir ? scanFrameDirectory(framesDir, req.framesPattern) : null;
1155
+ const sequence = scan ? measureFrameSequence(scan.files) : null;
1156
+ // The FRAMES path needs ffmpeg and nothing else — the caller already rendered.
1157
+ const availability = framesDir ? framesAvailability() : motionAvailability();
343
1158
  if (!availability.ok) {
344
1159
  return { ok: false, error: `motion: cannot render — missing ${availability.missing.join(', ')}.`, hint: availability.hint };
345
1160
  }
1161
+ if (framesDir && !sequence) {
1162
+ return { ok: false, error: `motion: ${frameScanHint(framesDir, req.framesPattern)}` };
1163
+ }
346
1164
  const html = String(req.html ?? '');
347
- if (!html.trim())
1165
+ if (!framesDir && !html.trim())
348
1166
  return { ok: false, error: 'motion: nothing to render (empty source).' };
349
- const plan = buildFramePlan({ fps: req.fps, duration_ms: req.duration_ms });
350
- const { width, height } = resolveFrameSize({ width: req.width, height: req.height, aspect_ratio: req.aspect_ratio });
1167
+ // A frame sequence states its own length; fps is the caller's, because a
1168
+ // directory of PNGs cannot know the rate it was authored for.
1169
+ const plan = sequence
1170
+ ? (() => {
1171
+ const { fps } = buildFramePlan({ fps: req.fps });
1172
+ return { fps, frames: sequence.files.length, durationMs: Math.round((sequence.files.length / fps) * 1000) };
1173
+ })()
1174
+ : buildFramePlan({ fps: req.fps, duration_ms: req.duration_ms });
1175
+ const sized = sequence && sequence.width > 0
1176
+ ? { width: sequence.width, height: sequence.height }
1177
+ : resolveFrameSize({ width: req.width, height: req.height, aspect_ratio: req.aspect_ratio });
1178
+ const { width, height } = sized;
351
1179
  const format = req.format === 'gif' || req.format === 'webm' ? req.format : 'mp4';
352
1180
  const workDir = mkdtempSync(join(tmpdir(), 'nuvira-motion-'));
353
1181
  const outDir = artifactsDir('motion', req.cwd);
@@ -355,37 +1183,62 @@ export async function renderMotion(req) {
355
1183
  const finalName = `${base}.${format}`;
356
1184
  const outPath = join(outDir, finalName);
357
1185
  const warnings = [];
1186
+ // Kept separately from `warnings` because they are the ones that EXPLAIN a failed
1187
+ // encode: mixed formats and mismatched sizes are the reasons ffmpeg dies, and an
1188
+ // error that hides them sends the caller to debug ffmpeg instead of their frames.
1189
+ const scanWarnings = [];
358
1190
  let seekMode = 'none';
1191
+ let pattern;
1192
+ // An existing audio file (music, SFX, a voice-over) rides the FIRST encode, and
1193
+ // the caption-burn re-encode too — the burn rebuilds the video from the frames,
1194
+ // so audio attached only to the first pass would be discarded by it.
1195
+ const bed = typeof req.audioPath === 'string' && req.audioPath.trim() ? req.audioPath.trim() : undefined;
1196
+ if (bed && !existsSync(bed)) {
1197
+ warnings.push(`the audio bed ${bed} does not exist — the render is silent`);
1198
+ }
1199
+ const audioBed = bed && existsSync(bed) ? bed : undefined;
359
1200
  try {
360
- const browser = await (_launcher ?? launchChromium)({ width, height });
361
- let page = null;
362
- try {
363
- page = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: 1 });
364
- // The runner goes in the markup, ahead of the animation's own script: it has
365
- // to exist before the page tries to schedule its first frame.
366
- await page.setContent(injectRunner(html), { waitUntil: 'load' });
367
- await page.evaluate(MOTION_READY_SCRIPT);
368
- const clip = { x: 0, y: 0, width, height };
369
- for (let i = 0; i < plan.frames; i += 1) {
370
- const t = frameTimestampMs(i, plan.fps);
371
- const how = await page.evaluate(seekScript(t));
372
- if (typeof how === 'string' && how !== 'none')
373
- seekMode = how;
374
- await page.screenshot({ path: join(workDir, `frame-${String(i + 1).padStart(5, '0')}.png`), clip });
1201
+ if (sequence) {
1202
+ // THE CALLER'S OWN RENDERER. The frames are measured, size-checked and
1203
+ // linked under ffmpeg's expected names; nothing is captured and nothing is
1204
+ // seeked, because the animation already happened in the caller's program.
1205
+ if (sequence.width === 0) {
1206
+ warnings.push(`the frame size could not be read from ${basename(sequence.files[0])} — report it from the source instead of trusting a default`);
1207
+ }
1208
+ else if (sequence.width % 2 !== 0 || sequence.height % 2 !== 0) {
1209
+ warnings.push(`${sequence.width}×${sequence.height} has an odd dimension, which H.264's chroma subsampling rejects — the encode may fail`);
1210
+ }
1211
+ if (sequence.mismatched > 0) {
1212
+ warnings.push(`${sequence.mismatched} of ${sequence.files.length} frames differ in size from the first one, and the encoded video will show that`);
1213
+ }
1214
+ warnings.push(`the frames came from the caller's renderer, so there is no seek hook here to verify — reproducibility is the renderer's contract, not this module's`);
1215
+ // What the DIRECTORY is, before what is in it: several interleaved sequences,
1216
+ // a numbering gap, mixed formats and skipped subdirectories all encode into a
1217
+ // file that plays, so nothing downstream can catch them but this.
1218
+ if (scan) {
1219
+ scanWarnings.push(...frameScanWarnings(scan));
1220
+ warnings.push(...scanWarnings);
375
1221
  }
1222
+ seekMode = 'external';
1223
+ pattern = linkFramesInto(sequence.files, workDir);
1224
+ }
1225
+ else {
1226
+ const times = Array.from({ length: plan.frames }, (_, i) => frameTimestampMs(i, plan.fps));
1227
+ seekMode = await captureFramesInto({ html, width, height, times, dir: workDir });
376
1228
  if (seekMode === 'none') {
377
1229
  warnings.push('the animation is not seekable (no window.__motion.seek, no requestAnimationFrame loop and no Web Animations), ' +
378
1230
  'so this render is a still sequence — see the motion skill for the seek contract');
379
1231
  }
1232
+ pattern = join(workDir, 'frame-%05d.png');
380
1233
  }
381
- finally {
382
- await page?.close().catch(() => undefined);
383
- await browser.close().catch(() => undefined);
384
- }
385
- const pattern = join(workDir, 'frame-%05d.png');
386
- const encoded = await runFfmpeg(buildFfmpegArgs({ fps: plan.fps, pattern, out: outPath, format, crf: req.crf }));
1234
+ const encoded = await runFfmpeg(buildFfmpegArgs({ fps: plan.fps, pattern, out: outPath, format, crf: req.crf, ...(audioBed ? { audioPath: audioBed } : {}) }));
387
1235
  if (encoded.code !== 0 || !existsSync(outPath)) {
388
- return { ok: false, error: `motion: ffmpeg failed to encode the frames — ${encoded.stderr.trim().split('\n').slice(-3).join(' ')}` };
1236
+ return {
1237
+ ok: false,
1238
+ error: `motion: ffmpeg failed to encode the frames — ${encoded.stderr.trim().split('\n').slice(-3).join(' ')}` +
1239
+ // The likely CAUSE, before the ffmpeg noise the caller cannot act on.
1240
+ (scanWarnings.length > 0 ? ` Your frame directory is the likely reason: ${scanWarnings.join(' ')}` : ''),
1241
+ };
389
1242
  }
390
1243
  // Captions BEFORE narration, and the order is the whole point: burning them
391
1244
  // in re-encodes the video from the PNG frames, so an audio track muxed onto
@@ -397,12 +1250,32 @@ export async function renderMotion(req) {
397
1250
  srtPath = join(outDir, `${base}.srt`);
398
1251
  writeFileSync(srtPath, buildSrt(req.captions), 'utf-8');
399
1252
  if (req.burn_captions) {
400
- const burned = join(workDir, `burned.${format}`);
401
- const res = await runFfmpeg(buildFfmpegArgs({ fps: plan.fps, pattern, out: burned, format, crf: req.crf, srtPath, burnCaptions: true }));
402
- if (res.code === 0 && existsSync(burned))
403
- copyFileSync(burned, outPath);
404
- else
405
- warnings.push(`captions were written to ${basename(srtPath)} but could not be burned in (this ffmpeg may lack libass)`);
1253
+ const burner = ffmpegWithSubtitles();
1254
+ if (!burner) {
1255
+ // Names the two real fixes. "This ffmpeg may lack libass" left the user to
1256
+ // work out which ffmpeg, which build, and what to install.
1257
+ warnings.push(`captions were written to ${basename(srtPath)} but could NOT be burned in: no ffmpeg on this machine has the libass ` +
1258
+ `subtitles filter (macOS: 'brew install ffmpeg-full' — this then uses it automatically; or point NUVIRA_FFMPEG at a build with libass)`);
1259
+ }
1260
+ else {
1261
+ const burned = join(workDir, `burned.${format}`);
1262
+ const res = await runFfmpeg(buildFfmpegArgs({
1263
+ fps: plan.fps,
1264
+ pattern,
1265
+ out: burned,
1266
+ format,
1267
+ crf: req.crf,
1268
+ srtPath,
1269
+ burnCaptions: true,
1270
+ ...(audioBed ? { audioPath: audioBed } : {}),
1271
+ }), burner);
1272
+ if (res.code === 0 && existsSync(burned))
1273
+ copyFileSync(burned, outPath);
1274
+ else {
1275
+ warnings.push(`captions were written to ${basename(srtPath)} but the burn failed with ${basename(burner)} — ` +
1276
+ `${res.stderr.trim().split('\n').slice(-2).join(' ')}`);
1277
+ }
1278
+ }
406
1279
  }
407
1280
  }
408
1281
  // Narration: synthesized with the SAME local engine the `speak` tool uses, and
@@ -425,6 +1298,8 @@ export async function renderMotion(req) {
425
1298
  format,
426
1299
  bytes,
427
1300
  seek: seekMode,
1301
+ frameSource: sequence ? 'frames' : 'html',
1302
+ frameCount: plan.frames,
428
1303
  warnings,
429
1304
  };
430
1305
  }
@@ -438,6 +1313,182 @@ export async function renderMotion(req) {
438
1313
  rmSync(workDir, { recursive: true, force: true });
439
1314
  }
440
1315
  }
1316
+ /**
1317
+ * Capture the page at each timestamp, numbered from 1, and report its seek mode.
1318
+ *
1319
+ * One implementation for both callers: a full render asks for every frame, and
1320
+ * the contact sheet asks for a dozen — the difference is the TIMES, not the
1321
+ * mechanism, so the two can never disagree about what "seekable" means.
1322
+ */
1323
+ async function captureFramesInto(o) {
1324
+ const browser = await (_launcher ?? launchChromium)({ width: o.width, height: o.height });
1325
+ let seek = 'none';
1326
+ let page = null;
1327
+ try {
1328
+ page = await browser.newPage({ viewport: { width: o.width, height: o.height }, deviceScaleFactor: 1 });
1329
+ // The runner goes in the markup, ahead of the animation's own script: it has
1330
+ // to exist before the page tries to schedule its first frame.
1331
+ await page.setContent(injectRunner(o.html), { waitUntil: 'load' });
1332
+ await page.evaluate(MOTION_READY_SCRIPT);
1333
+ const clip = { x: 0, y: 0, width: o.width, height: o.height };
1334
+ for (let i = 0; i < o.times.length; i += 1) {
1335
+ const how = await page.evaluate(seekScript(o.times[i]));
1336
+ if (typeof how === 'string' && how !== 'none')
1337
+ seek = how;
1338
+ await page.screenshot({ path: join(o.dir, `frame-${String(i + 1).padStart(5, '0')}.png`), clip });
1339
+ }
1340
+ }
1341
+ finally {
1342
+ await page?.close().catch(() => undefined);
1343
+ await browser.close().catch(() => undefined);
1344
+ }
1345
+ return seek;
1346
+ }
1347
+ /**
1348
+ * The most readable tiling: at most four columns, and as few empty cells as the
1349
+ * count allows (9 tiles are 3×3, not 4×3 with three blanks, because a blank cell
1350
+ * reads as a frame that failed to render).
1351
+ */
1352
+ export function gridFor(tiles) {
1353
+ const count = Math.max(1, Math.round(tiles));
1354
+ let best = { cols: 1, rows: count, waste: 0 };
1355
+ for (let cols = 1; cols <= Math.min(4, count); cols += 1) {
1356
+ const rows = Math.ceil(count / cols);
1357
+ const waste = cols * rows - count;
1358
+ if (waste < best.waste || (waste === best.waste && cols > best.cols))
1359
+ best = { cols, rows, waste };
1360
+ }
1361
+ return { cols: best.cols, rows: best.rows };
1362
+ }
1363
+ /** Evenly spaced picks, first and last included — the ends matter most. */
1364
+ export function sampleFrames(items, count) {
1365
+ if (items.length <= count)
1366
+ return items.slice();
1367
+ if (count <= 1)
1368
+ return [items[0]];
1369
+ const picked = [];
1370
+ for (let i = 0; i < count; i += 1)
1371
+ picked.push(items[Math.round((i * (items.length - 1)) / (count - 1))]);
1372
+ return picked;
1373
+ }
1374
+ /** The ffmpeg argv for a tiled contact sheet: one PNG, `cols`×`rows` frames. */
1375
+ export function buildTileArgs(o) {
1376
+ return [
1377
+ '-y',
1378
+ '-hide_banner',
1379
+ '-loglevel',
1380
+ 'error',
1381
+ '-start_number',
1382
+ '1',
1383
+ '-i',
1384
+ o.pattern,
1385
+ // `-2` keeps the aspect and forces an even height, which the PNG encoder and
1386
+ // the viewer both prefer to a half-pixel row.
1387
+ '-vf',
1388
+ `scale=${o.tileWidth}:-2,tile=${o.cols}x${o.rows}`,
1389
+ '-frames:v',
1390
+ '1',
1391
+ o.out,
1392
+ ];
1393
+ }
1394
+ /**
1395
+ * Render a contact sheet of keyframes so the model can SEE what it made.
1396
+ *
1397
+ * Works for both sources: a seekable HTML page (a dozen seeks instead of the
1398
+ * whole timeline, so reviewing is seconds rather than minutes) and a caller's
1399
+ * frame sequence (evenly sampled from what is already on disk).
1400
+ */
1401
+ export async function inspectMotion(req) {
1402
+ const tiles = clampInt(req.tiles, 2, 24, 12);
1403
+ const tileWidth = clampInt(req.tile_width, 120, 960, 480);
1404
+ const framesDir = typeof req.framesDir === 'string' && req.framesDir.trim() ? req.framesDir.trim() : undefined;
1405
+ const scan = framesDir ? scanFrameDirectory(framesDir, req.framesPattern) : null;
1406
+ const sequence = scan ? measureFrameSequence(scan.files) : null;
1407
+ const availability = framesDir ? framesAvailability() : motionAvailability();
1408
+ if (!availability.ok) {
1409
+ return { ok: false, error: `motion: cannot inspect — missing ${availability.missing.join(', ')}.`, hint: availability.hint };
1410
+ }
1411
+ if (framesDir && !sequence) {
1412
+ return { ok: false, error: `motion: ${frameScanHint(framesDir, req.framesPattern)}` };
1413
+ }
1414
+ const html = String(req.html ?? '');
1415
+ if (!framesDir && !html.trim()) {
1416
+ return { ok: false, error: 'motion: nothing to inspect — pass html (or html_path) or frames_dir.' };
1417
+ }
1418
+ const workDir = mkdtempSync(join(tmpdir(), 'nuvira-motion-inspect-'));
1419
+ const warnings = [];
1420
+ try {
1421
+ let pattern;
1422
+ let seek = 'none';
1423
+ let frameSource;
1424
+ let tiles0;
1425
+ let secondsPerTile;
1426
+ let { width, height } = resolveFrameSize({});
1427
+ if (sequence) {
1428
+ const picked = sampleFrames(sequence.files, tiles);
1429
+ const { fps } = buildFramePlan({ fps: req.fps });
1430
+ tiles0 = picked.length;
1431
+ frameSource = 'frames';
1432
+ seek = 'external';
1433
+ width = sequence.width;
1434
+ height = sequence.height;
1435
+ secondsPerTile = tiles0 > 1 ? sequence.files.length / fps / (tiles0 - 1) : 0;
1436
+ pattern = linkFramesInto(picked, workDir);
1437
+ warnings.push(`sampled ${picked.length} of ${sequence.files.length} frames from the caller's renderer`);
1438
+ // The sheet is the review step, so the directory's problems belong on it too:
1439
+ // a contact sheet of a wrongly-ordered sequence should not look fine.
1440
+ if (scan)
1441
+ warnings.push(...frameScanWarnings(scan));
1442
+ }
1443
+ else {
1444
+ const plan = buildFramePlan({ fps: req.fps, duration_ms: req.duration_ms });
1445
+ const size = resolveFrameSize({ width: req.width, height: req.height, aspect_ratio: undefined });
1446
+ width = size.width;
1447
+ height = size.height;
1448
+ tiles0 = Math.min(tiles, plan.frames);
1449
+ secondsPerTile = tiles0 > 1 ? plan.durationMs / 1000 / (tiles0 - 1) : 0;
1450
+ // Sample the TIMELINE, not every frame: reviewing a 20s piece costs a dozen
1451
+ // seeks instead of six hundred captures.
1452
+ const times = Array.from({ length: tiles0 }, (_, i) => (plan.durationMs * i) / Math.max(1, tiles0 - 1));
1453
+ seek = await captureFramesInto({ html, width, height, times, dir: workDir });
1454
+ frameSource = 'html';
1455
+ pattern = join(workDir, 'frame-%05d.png');
1456
+ if (seek === 'none')
1457
+ warnings.push('the animation is not seekable, so these keyframes are of a still sequence');
1458
+ }
1459
+ const outDir = artifactsDir('motion', req.cwd);
1460
+ const base = req.out_name ? safeArtifactName(`${req.out_name}-sheet`, '') : safeArtifactName('motion-sheet', '');
1461
+ const out = join(outDir, `${base}.png`);
1462
+ const { cols, rows } = gridFor(tiles0);
1463
+ const res = await runFfmpeg(buildTileArgs({ pattern, tileWidth, cols, rows, out }));
1464
+ if (res.code !== 0 || !existsSync(out)) {
1465
+ return {
1466
+ ok: false,
1467
+ error: `motion: ffmpeg could not build the contact sheet — ${res.stderr.trim().split('\n').slice(-3).join(' ')}`,
1468
+ };
1469
+ }
1470
+ return {
1471
+ ok: true,
1472
+ file: out,
1473
+ tiles: tiles0,
1474
+ cols,
1475
+ rows,
1476
+ secondsPerTile,
1477
+ frameSource,
1478
+ seek,
1479
+ width,
1480
+ height,
1481
+ totalFrames: sequence ? sequence.files.length : buildFramePlan({ fps: req.fps, duration_ms: req.duration_ms }).frames,
1482
+ warnings,
1483
+ };
1484
+ }
1485
+ catch (err) {
1486
+ return { ok: false, error: `motion: inspect failed — ${err instanceof Error ? err.message : String(err)}` };
1487
+ }
1488
+ finally {
1489
+ rmSync(workDir, { recursive: true, force: true });
1490
+ }
1491
+ }
441
1492
  let _speak = null;
442
1493
  /** Test seam: replace speech synthesis (so the mux path is testable offline). */
443
1494
  export function setSpeakForTests(speak) {
@@ -479,7 +1530,11 @@ export function saveMotionManifest(manifest, cwd) {
479
1530
  mkdirSync(dir, { recursive: true });
480
1531
  const file = join(dir, 'manifest.json');
481
1532
  writeFileSync(file, JSON.stringify(manifest, null, 2), 'utf-8');
482
- writeFileSync(join(dir, 'source.html'), manifest.source, 'utf-8');
1533
+ // Only when there IS an html source: a frames render would otherwise leave an
1534
+ // empty `source.html` behind, which reads as "the source was empty" rather
1535
+ // than "the source was never here".
1536
+ if (manifest.source && manifest.source.trim())
1537
+ writeFileSync(join(dir, 'source.html'), manifest.source, 'utf-8');
483
1538
  return file;
484
1539
  }
485
1540
  export function loadMotionManifest(id, cwd) {