motigenjs 0.1.0 → 0.1.1

package/README.md

@@ -61,6 +61,7 @@ Linux). Without it, record in a container: `backend: 'docker'`.
 | `motigen preview [--port 4310] [--open]` | A player over the project: scrub, play with `audio/mix.wav`, switch formats, render and export events from buttons. |
 | `motigen frames -t 1,2.5,10` | Stills into `shots/` (`--png`, `--every 5`, `--element '#terminal'` with a transparent background, `--scale 2`). |
 | `motigen render` | The video to `out/<name>.mp4`: `-j N` pages in parallel (default: half the cores, at most 4), `--range 10-20`, `--audio file.wav` or the project's `audio/mix.wav`, `--crf`, `--preset`. |
+| `motigen stability -t 3,10` | Renders consecutive frames at those moments and reports what changed between them (`--every 2`, `--frames 3`, `--still` to fail on any change). |
 | `motigen events` | The page's `events()` into `audio/events.json`: voice cues, clicks, keys, Enter presses, effects. |
 | `motigen record [take.mjs]` | Runs a take script; it imports `{ Term, Browser, sleep }` from `motigenjs/record`. |
 | `motigen vo [lines.txt]` | Narration: one ElevenLabs call for the whole script, split per line into `audio/vo/` with `vo.json`. `vo split` uses a saved response, `vo import` your own recordings, `vo check` flags breathy or garbled lines. |
@@ -146,6 +147,22 @@ click / key / Enter sounds for what the recorder logged (synthesised when `audio
 bed with a crossfade, ducks it under the voice and masters with ffmpeg's two-pass loudnorm. The levels, the
 ducking and the target live under `"mix"` in `motigen.json`. [docs/audio.md](docs/audio.md).
 
+## Stillness
+
+A still shot has to repeat the same pixels frame after frame; the smallest shimmer on text reads as jitter once
+it is encoded. motigen is built so that it does not happen, and ships the check:
+
+- Every frame is a pure function of `t`: nothing on screen may depend on the clock, on CSS animations or on
+  unseeded randomness.
+- The guide player snaps its camera to whole pixels and a fixed scale grid, so a slow pan moves in clean steps
+  and a hold repeats one transform; the canvas kit keeps hand-drawn strokes on one seed (no "line boil"); the
+  templates settle every animated value to an exact number.
+- The encoder puts keyframes every 2 s and nowhere else (`--gop`), so fine texture does not pulse on holds.
+- `motigen stability -t 3,10,20` renders consecutive frames at those moments and reports the share of pixels
+  that changed, with a box around the change and a `-diff.png` that shows it brightened; `--still` fails when a
+  moment is not perfectly still. A cursor, a caret or a spinner show up as small boxes; jitter shows up as a
+  small change spread across text that should not move.
+
 ## Why not …
 
 - **Remotion**: React, a bundler and a licence with limits for companies. motigen takes any page, needs no build

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motigenjs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Video as code for developers and their coding agents: a web page draws frame t, headless Chrome renders it to MP4; real terminals and browsers are recorded, narration and the mix come from the same timeline.",
   "type": "module",
   "bin": {

package/runtime/canvas/kit.js

@@ -19,7 +19,8 @@ canvas.width = W; canvas.height = H;
 export const ctx = canvas.getContext('2d', { alpha: false });
 export const off = (w, h) => { const c = new OffscreenCanvas(w, h); return [c, c.getContext('2d')]; };
 
-// Line boil (drawings re-seeded on twos) reads as jitter on video, so it is off unless ?boil=1.
+// Line boil (hand-drawn strokes re-seeded 12 times a second) reads as jitter on video, so it is off: every stroke
+// keeps one seed for the whole film and a still shot repeats the same pixels. ?boil=1 turns it on for experiments.
 export const BOIL = Q.get('boil') === '1';
 export const bt = f => (BOIL ? Math.floor(f / 2) : 0);
 export const on2 = f => Math.floor(f / 2) * 2;               // quantise a frame to twos

package/runtime/guide/player.js

@@ -213,8 +213,8 @@ async function renderAt(t) {
   const k = switching ? ease(lt / 0.45) : 1;
   const front = active === 'browser' ? winB : winT, back = active === 'browser' ? winT : winB;
   front.style.zIndex = 2; back.style.zIndex = 1;
-  front.style.opacity = k; front.style.transform = `translateY(${(1 - k) * 36}px) scale(${0.985 + 0.015 * k})`;
-  back.style.opacity = switching ? 1 - k * 0.999 : 0; back.style.transform = `scale(${1 - 0.02 * k})`;
+  front.style.opacity = k; front.style.transform = k === 1 ? 'none' : `translateY(${Math.round((1 - k) * 36)}px) scale(${0.985 + 0.015 * k})`;
+  back.style.opacity = switching ? 1 - k * 0.999 : 0; back.style.transform = k === 1 ? 'none' : `scale(${1 - 0.02 * k})`;
 
   // browser content
   const bShot = shot.kind === 'browser' ? shot : switching && prev.kind === 'browser' ? prev : null;
@@ -261,11 +261,13 @@ async function renderAt(t) {
   if (tShot) await termAt(tShot === shot ? srcOf(shot, lt) : srcOf(tShot, tShot.dur));
   else await termAt(0);
 
-  // camera
+  // camera. The translation is snapped to whole pixels and the scale to 1/10000: a slow drift then moves in
+  // clean one-pixel steps and a hold repeats the exact same transform every frame, so text is never re-rasterised
+  // at a slightly different sub-pixel offset from one frame to the next (that reads as jitter on video).
   const place = (el, z, unit) => {
-    const [s, x, y] = z; const cx = x * unit, cy = y * unit;
+    const [s0, x, y] = z; const s = Math.round(s0 * 1e4) / 1e4, cx = x * unit, cy = y * unit;
     // keep the zoomed content inside the window: no empty edges
-    const tx = clamp(VW / 2 - cx * s, VW - VW * s, 0), ty = clamp(VH / 2 - cy * s, VH - VH * s, 0);
+    const tx = Math.round(clamp(VW / 2 - cx * s, VW - VW * s, 0)), ty = Math.round(clamp(VH / 2 - cy * s, VH - VH * s, 0));
     el.style.transform = s === 1 ? 'none' : `translate(${tx}px, ${ty}px) scale(${s})`;
   };
   const zb = shot.kind === 'browser' ? zoomAt(shot, lt) : switching && prev.kind === 'browser' ? zoomAt(prev, prev.dur) : [1, 800, 450];
@@ -281,14 +283,14 @@ async function renderAt(t) {
   if (ch) {
     chapter.querySelector('.n').textContent = ch[0]; chapter.querySelector('.t').textContent = ch[1];
     const kc = ease((t - chapterSince) / 0.4);
-    chapter.style.opacity = kc; chapter.style.transform = `translateX(${(1 - kc) * -24}px)`;
+    chapter.style.opacity = kc; chapter.style.transform = `translateX(${Math.round((1 - kc) * -24)}px)`;
   }
   const kb = (shot.keys || []).find(([a, b]) => lt >= a && lt < b);
   key.style.display = kb ? 'flex' : 'none';
   if (kb) {
     key.querySelector('kbd').textContent = kb[2]; key.querySelector('span').textContent = kb[3] || '';
     const kk = Math.min(ease((lt - kb[0]) / 0.25), 1 - ease((lt - (kb[1] - 0.25)) / 0.25));
-    key.style.opacity = kk; key.style.transform = `translateX(-50%) translateY(${(1 - kk) * -14}px)`;
+    key.style.opacity = kk; key.style.transform = `translateX(-50%) translateY(${Math.round((1 - kk) * -14)}px)`;
   }
   const nt = shot.note;
   note.textContent = nt || ''; note.style.opacity = nt && shot.kind !== 'card' ? Math.min(ease(lt / 0.4), 1 - ease((lt - shot.dur + 0.4) / 0.4)) : 0;

package/skill/SKILL.md

@@ -22,7 +22,9 @@ Commands: `init`, `record`, `preview`, `frames`, `events`, `vo`, `mix`, `srt`, `
    **Canvas:** write `film.js` (`load`, `LAYOUTS` for both formats, `render(ctx, f)`, `mixSpec`); `VO_CUES` put the
    first word of each line on a frame. **Dom:** edit `film.html`.
 4. **Look before rendering.** `motigen frames -t 1,5,12` and open the JPEGs; `motigen preview` for scrubbing.
-   Check both formats when the project has them (`--fmt v`).
+   Check both formats when the project has them (`--fmt v`). Then `motigen stability -t <a few hold moments>
+   --still`: every hold must report `still`; a `small` change on text that should not move is jitter — find the
+   value that still changes (a transform that never settles, a position computed from the clock, line boil).
 5. **Sound.** `motigen vo` (needs `ELEVENLABS_API_KEY` and the voice id) or `motigen vo import` for recordings;
    `motigen vo check`; `motigen events`; `motigen mix`. Listen: `audio/mix.wav` should sit at −14 LUFS.
 6. **Build.** `motigen build` renders every format and writes the `.srt`. Report the output paths and lengths.

package/src/cli.js

@@ -16,6 +16,7 @@ const USAGE = `motigen ${VERSION} — video as code
   motigen preview [--port 4310] [--open]     player: scrub, sound, formats, a render button
   motigen frames -t 1,2.5,10 [-o shots]      stills at those seconds (jpeg; --png; --element '#terminal')
   motigen render [-o out.mp4]                the video (--fps 30 --workers 4 --audio audio/mix.wav --range 10-20)
+  motigen stability -t 3,10 [--every 2]      do still moments stay still? pixels changed between consecutive frames (--still: fail if not)
   motigen events [-o audio/events.json]      the timeline's sound events, for the mix
   motigen vo [audio/lines.txt]               narration: one ElevenLabs call, split per line into audio/vo/ ($ELEVENLABS_API_KEY)
   motigen vo split <resp.json> <lines.txt>   split a saved with-timestamps response instead of calling the API
@@ -36,7 +37,7 @@ Options:
   --query "fmt=v"        query string for the page
   --scale N              device scale factor for stills (default 1)
   --no-audio             render without sound even if audio/mix.wav exists
-  --crf N --preset P     x264 quality (default 14, slow)
+  --crf N --preset P     x264 quality (default 14, slow); --gop <s> keyframe interval in seconds (default 2)
   -j, --workers N        pages rendering in parallel (default: half the cores, at most 4)
   --channel chrome       installed Chrome instead of Playwright's Chromium
   --no-gpu / --gpu       GPU flags (default: on under Windows)
@@ -44,6 +45,7 @@ Options:
   --timeout <s>          seconds to wait for window.__film.ready (default 60)
   --voice <id> --model <id> --seed <n>   TTS settings (also "vo": {…} in motigen.json)
   --limit <n>            vo check: flatness above this is flagged (default 0.12)
+  --frames <n>           stability: consecutive frames per sample (default 3); --threshold <0-255> pixel change that counts (8)
 
 motigen.json may also hold "vo": { "voice", "model", "seed", "settings" }, "mix": { levels, ducking, target } and
 "spellings": [["Acme Cloud dot com", "acmecloud.com"]] for the subtitles.
@@ -57,6 +59,7 @@ const OPTIONS = {
   crf: { type: 'string' }, preset: { type: 'string' }, channel: { type: 'string' }, gpu: { type: 'boolean' }, 'no-gpu': { type: 'boolean' },
   ffmpeg: { type: 'string' }, timeout: { type: 'string' }, port: { type: 'string' }, open: { type: 'boolean' }, force: { type: 'boolean' },
   voice: { type: 'string' }, model: { type: 'string' }, seed: { type: 'string' }, limit: { type: 'string' },
+  frames: { type: 'string' }, threshold: { type: 'string' }, still: { type: 'boolean' }, gop: { type: 'string' },
   help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
 };
 
@@ -109,6 +112,23 @@ const commands = {
     for (const f of files) console.log(show(f));
   },
 
+  async stability(v, pos) {
+    const t = await target(v, v.fmt?.[0]);
+    const times = (v.times || pos[0] || '').split(/[,\s]+/).filter(Boolean).map(Number);
+    const every = num(v.every, 'every', 0);
+    if (!times.length && !every) fail('stability: give the moments, e.g. -t 3,10,20 (or --every 2)');
+    const { stability } = await import('./stability.js');
+    const rows = await stability({ ...open(t), fps: t.fps, times, every, frames: num(v.frames, 'frames', 3), threshold: num(v.threshold, 'threshold', 8), out: resolve(t.project, v.out || 'stability'), ffmpeg: t.ffmpeg });
+    let moving = 0;
+    for (const r of rows) {
+      const parts = r.pairs.map(p => `${p.pct.toFixed(2)}%${p.box ? ` @${p.box[0]},${p.box[1]}-${p.box[2]},${p.box[3]}` : ''}`);
+      console.log(`${r.t.toFixed(2).padStart(7)} s  ${r.verdict.padEnd(7)} ${parts.join(' | ')}`);
+      if (r.verdict !== 'still') moving++;
+    }
+    console.log(`${rows.length} moments · ${rows.length - moving} still · ${moving} with changes (a -diff.png next to each changed frame shows what moved) · ${show(resolve(t.project, v.out || 'stability'))}`);
+    if (v.still && moving) { console.error(`--still: ${moving} of ${rows.length} moments are not still`); process.exitCode = 2; }
+  },
+
   async events(v) {
     const t = await target(v, v.fmt?.[0]);
     const out = resolve(t.project, v.out || join(t.cfg.audio, 'events.json'));
@@ -121,7 +141,7 @@ const commands = {
     const out = resolve(t.project, v.out || t.outDefault);
     const audio = v['no-audio'] ? null : v.audio ? resolve(t.project, v.audio) : defaultAudio(t.cfg);
     const bar = progress('render');
-    const r = await renderVideo({ ...open(t), out, fps: t.fps, audio, crf: num(v.crf, 'crf', 14), preset: v.preset || 'slow', range: parseRange(v.range), workers: num(v.workers, 'workers', defaultWorkers()), ffmpeg: t.ffmpeg, onProgress: bar });
+    const r = await renderVideo({ ...open(t), out, fps: t.fps, audio, crf: num(v.crf, 'crf', 14), preset: v.preset || 'slow', gop: num(v.gop, 'gop', 2), range: parseRange(v.range), workers: num(v.workers, 'workers', defaultWorkers()), ffmpeg: t.ffmpeg, onProgress: bar });
     bar(r.frames, r.frames, true);
     console.log(`${show(r.out)} · ${r.frames} frames @ ${r.fps} fps${audio ? ' · audio ' + relative(t.project, audio) : ' · silent'} · ${r.seconds.toFixed(0)} s`);
   },

package/src/render.js

@@ -124,13 +124,16 @@ function run(cmd, args) {
   });
 }
 
-const x264 = (fps, crf, preset) => ['-c:v', 'libx264', '-preset', preset, '-crf', String(crf), '-x264-params', 'aq-mode=3:aq-strength=0.9', '-pix_fmt', 'yuv420p', '-profile:v', 'high', '-g', String(fps * 2), '-movflags', '+faststart'];
+// Keyframes every `gop` seconds, and only there (no scene-cut keyframes): each I-frame re-encodes fine texture a
+// little differently, which reads as a pulse on a still shot, so they are kept rare and regular. 1 s made paper
+// grain breathe; 2 s is quiet and still seeks fine.
+const x264 = (fps, crf, preset, gop = 2) => ['-c:v', 'libx264', '-preset', preset, '-crf', String(crf), '-x264-params', 'aq-mode=3:aq-strength=0.9:scenecut=0', '-pix_fmt', 'yuv420p', '-profile:v', 'high', '-g', String(Math.max(1, Math.round(fps * gop))), '-movflags', '+faststart'];
 // audio padded to the video's length, then cut to it: the video always decides the duration
 const audioArgs = audio => (audio ? ['-i', audio, '-map', '0:v', '-map', '1:a', '-c:a', 'aac', '-b:a', '256k', '-ar', '48000', '-af', 'apad', '-shortest'] : []);
 
 /** Frames [from, to) of one open film → x264 mp4 (with audio when given). */
-export async function encodeRange(film, { from, to, fps, out, audio, crf = 14, preset = 'slow', ffmpeg = 'ffmpeg', onFrame }) {
-  const args = ['-v', 'error', '-y', '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'png', '-i', '-', ...audioArgs(audio), ...x264(fps, crf, preset), out];
+export async function encodeRange(film, { from, to, fps, out, audio, crf = 14, preset = 'slow', gop = 2, ffmpeg = 'ffmpeg', onFrame }) {
+  const args = ['-v', 'error', '-y', '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'png', '-i', '-', ...audioArgs(audio), ...x264(fps, crf, preset, gop), out];
   let err = '', failed = null;
   const ff = spawn(ffmpeg, args, { stdio: ['pipe', 'ignore', 'pipe'] });
   ff.stderr.on('data', d => { err += d; });
@@ -157,7 +160,7 @@ export async function encodeRange(film, { from, to, fps, out, audio, crf = 14, p
  * Render the whole film (or `range` = [a, b] seconds) to `out`.
  * @returns {Promise<{ out: string, frames: number, fps: number, seconds: number }>}
  */
-export async function renderVideo({ out, fps, audio, crf = 14, preset = 'slow', range, workers = 1, ffmpeg = 'ffmpeg', onProgress, ...open }) {
+export async function renderVideo({ out, fps, audio, crf = 14, preset = 'slow', gop = 2, range, workers = 1, ffmpeg = 'ffmpeg', onProgress, ...open }) {
   const t0 = Date.now();
   out = resolve(out);
   const browser = await launch({ channel: open.channel, gpu: open.gpu });
@@ -173,7 +176,7 @@ export async function renderVideo({ out, fps, audio, crf = 14, preset = 'slow',
     workers = Math.max(1, Math.min(workers | 0 || 1, n));
     await mkdir(dirname(out), { recursive: true });
     if (workers === 1) {
-      await encodeRange(films[0], { from: first, to: last, fps, out, audio, crf, preset, ffmpeg, onFrame: i => onProgress?.(i, n) });
+      await encodeRange(films[0], { from: first, to: last, fps, out, audio, crf, preset, gop, ffmpeg, onFrame: i => onProgress?.(i, n) });
     } else {
       const chunk = Math.ceil(n / workers);
       while (films.length < workers) films.push(await openFilm({ ...open, browser }));
@@ -183,7 +186,7 @@ export async function renderVideo({ out, fps, audio, crf = 14, preset = 'slow',
         if (from >= to) return null;
         const part = `${out}.part${String(w).padStart(2, '0')}.mp4`;
         parts.push(part);
-        return encodeRange(film, { from, to, fps, out: part, crf, preset, ffmpeg, onFrame: i => { done[w] = i; onProgress?.(done.reduce((x, y) => x + y, 0), n); } });
+        return encodeRange(film, { from, to, fps, out: part, crf, preset, gop, ffmpeg, onFrame: i => { done[w] = i; onProgress?.(done.reduce((x, y) => x + y, 0), n); } });
       }));
       const list = `${out}.parts.txt`;
       await writeFile(list, parts.map(p => `file '${p.replace(/\\/g, '/').replace(/'/g, "'\\''")}'`).join('\n') + '\n');

package/src/stability.js

@@ -0,0 +1,87 @@
+// Frame-to-frame stability: render a few consecutive frames at chosen moments and count the pixels that change
+// between them. A hold must give zero; a slow pan gives a steady, small, moving change; "jitter" is a small change
+// that comes and goes in a region that should be still (text re-rasterised at sub-pixel offsets, line boil,
+// anything that depends on wall-clock time). The difference rasters come from ffmpeg, so no image library is needed.
+import { spawn } from 'node:child_process';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { openFilm } from './render.js';
+
+/** Changed pixels between two PNG files: { pct, box: [x0, y0, x1, y1] | null }. */
+export async function diffPng(a, b, { threshold = 8, ffmpeg = process.env.MOTIGEN_FFMPEG || 'ffmpeg' } = {}) {
+  const raw = await new Promise((res, rej) => {
+    const chunks = []; let err = '';
+    const p = spawn(ffmpeg, ['-v', 'error', '-i', a, '-i', b, '-lavfi', '[0:v][1:v]blend=all_mode=difference,format=gray', '-f', 'rawvideo', '-'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    p.stdout.on('data', d => chunks.push(d)); p.stderr.on('data', d => { err += d; });
+    p.on('error', e => rej(e.code === 'ENOENT' ? new Error(`${ffmpeg} not found: install ffmpeg and put it in PATH (or set --ffmpeg / $MOTIGEN_FFMPEG)`) : e));
+    p.on('close', code => (code === 0 ? res(Buffer.concat(chunks)) : rej(new Error(`ffmpeg could not diff ${a} and ${b}: ${err.trim()}`))));
+  });
+  return countDiff(raw, threshold);
+}
+
+/** The size of a PNG from its header. */
+function pngSize(buf) { return [buf.readUInt32BE(16), buf.readUInt32BE(20)]; }
+
+export function countDiff(gray, threshold, width) {
+  const n = gray.length, w = width || Math.round(Math.sqrt(n * 16 / 9)) || 1;
+  let changed = 0, x0 = Infinity, y0 = Infinity, x1 = -1, y1 = -1;
+  for (let i = 0; i < n; i++) {
+    if (gray[i] > threshold) { changed++; const x = i % w, y = (i / w) | 0; if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y; }
+  }
+  return { pct: +(100 * changed / Math.max(1, n)).toFixed(3), changed, box: changed ? [x0, y0, x1, y1] : null };
+}
+
+/**
+ * @param {object} o
+ * @param {number[]} [o.times]   seconds to sample
+ * @param {number} [o.every]     sample every N seconds instead
+ * @param {number} [o.frames]    consecutive frames per sample (default 3)
+ * @param {string} o.out         folder for the PNGs
+ * @returns rows [{ t, pairs: [{ from, to, pct, box }], verdict }]
+ */
+export async function stability({ times = [], every = 0, frames = 3, out, threshold = 8, ffmpeg = process.env.MOTIGEN_FFMPEG || 'ffmpeg', fps: fpsOpt, ...open }) {
+  const film = await openFilm(open);
+  try {
+    const fps = fpsOpt || film.fps || 30;
+    if (every > 0) { times = []; for (let t = 0; t < film.dur; t += every) times.push(+t.toFixed(3)); }
+    await mkdir(out, { recursive: true });
+    const rows = [];
+    for (const t of times) {
+      const files = [];
+      let width = null;
+      for (let k = 0; k < frames; k++) {
+        const tk = Math.min(t + k / fps, film.dur - 1e-6);
+        await film.at(tk);
+        const buf = await film.shot('png');
+        width ||= pngSize(buf)[0];
+        const f = join(out, `t${t.toFixed(2).padStart(6, '0')}-${k}.png`);
+        await writeFile(f, buf);
+        files.push(f);
+      }
+      const pairs = [];
+      for (let k = 1; k < files.length; k++) {
+        // the difference raster (counted here) and, when anything changed, a picture of it with the changes
+        // brightened 16×, so the eye finds what moved
+        const diffFile = files[k].replace(/\.png$/, '-diff.png');
+        const raw = await new Promise((res, rej) => {
+          const chunks = []; let err = '';
+          const p = spawn(ffmpeg, ['-v', 'error', '-y', '-i', files[k - 1], '-i', files[k], '-filter_complex', "[0:v][1:v]blend=all_mode=difference,format=gray,split[a][b];[b]lutyuv=y='min(255,val*16)'[vis]", '-map', '[a]', '-f', 'rawvideo', '-', '-map', '[vis]', '-frames:v', '1', diffFile], { stdio: ['ignore', 'pipe', 'pipe'] });
+          p.stdout.on('data', d => chunks.push(d)); p.stderr.on('data', d => { err += d; });
+          p.on('error', e => rej(e.code === 'ENOENT' ? new Error(`${ffmpeg} not found: install ffmpeg and put it in PATH (or set --ffmpeg / $MOTIGEN_FFMPEG)`) : e));
+          p.on('close', code => (code === 0 ? res(Buffer.concat(chunks)) : rej(new Error(`ffmpeg could not diff frames: ${err.trim()}`))));
+        });
+        const d = countDiff(raw, threshold, width);
+        if (!d.changed) await rm(diffFile, { force: true });
+        pairs.push({ from: +(t + (k - 1) / fps).toFixed(3), to: +(t + k / fps).toFixed(3), ...d, diff: d.changed ? diffFile : null });
+      }
+      const max = Math.max(...pairs.map(p => p.pct));
+      // still: nothing changed. small: under 1 % of the frame changed (a cursor, a caret, a spinner, or jitter: look
+      // at the -diff.png). motion: more than that.
+      const verdict = max === 0 ? 'still' : max < 1 ? 'small' : 'motion';
+      rows.push({ t, pairs, verdict, files });
+    }
+    return rows;
+  } finally { await film.close(); }
+}
+
+export const resolveOut = (project, out) => resolve(project, out || 'stability');

package/templates/canvas/gitignore

@@ -4,3 +4,4 @@ audio/events.json
 audio/mix.wav
 audio/mix-raw.wav
 audio/vo/resp.json
+stability/

package/templates/dom/film.html

@@ -5,14 +5,16 @@
 <title>{{name}}</title>
 <style>
   /* The contract: window.__film = { ready, dur, fps, renderAt(t) }. Every value on screen is a pure function of t,
-     so motigen can render any frame in any order. No libraries, no build step: edit, reload, render. */
+     so motigen can render any frame in any order. No libraries, no build step: edit, reload, render.
+     Stillness: positions are whole pixels, transforms settle to exact values (scale(1), translate 0) and no CSS
+     animation or transition runs on its own; `motigen stability -t 7.5` checks that a hold repeats the same pixels. */
   @font-face { font-family: 'Geist'; font-weight: 500; font-display: block; src: url(/_motigen/vendor/geist-sans/files/geist-sans-latin-500-normal.woff2) format('woff2'); }
   @font-face { font-family: 'Geist'; font-weight: 800; font-display: block; src: url(/_motigen/vendor/geist-sans/files/geist-sans-latin-800-normal.woff2) format('woff2'); }
   @font-face { font-family: 'Geist Mono'; font-weight: 500; font-display: block; src: url(/_motigen/vendor/geist-mono/files/geist-mono-latin-500-normal.woff2) format('woff2'); }
   :root { --paper: #f6f2ea; --ink: #1f1d1a; --muted: #6b665d; --accent: #ee6a4a; }
   html, body { margin: 0; background: #000; }
   #stage { position: relative; width: 1920px; height: 1080px; overflow: hidden; background: radial-gradient(1400px 900px at 30% 20%, #fbf8f2, var(--paper) 60%, #ebe5d8); font-family: Geist, system-ui, sans-serif; color: var(--ink); }
-  .abs { position: absolute; will-change: transform, opacity; }
+  .abs { position: absolute; }
   #title { left: 160px; top: 300px; font-size: 128px; font-weight: 800; letter-spacing: -.045em; line-height: 1; transform-origin: 0 50%; }
   #sub { left: 164px; top: 470px; font-size: 40px; font-weight: 500; color: var(--muted); }
   .line { left: 164px; font-size: 34px; font-weight: 500; font-family: 'Geist Mono', monospace; }
@@ -49,9 +51,9 @@
     $('sub').style.opacity = prog(t, 1.4, 2.0); $('sub').style.transform = `translateY(${16 * (1 - out(prog(t, 1.4, 2.0)))}px)`;
     const lines = ['$ motigen frames -t 0,2,5', '$ motigen render', '$ motigen preview'];
     lines.forEach((s, i) => { const k = prog(t, 2.2 + i * 1.2, 3.0 + i * 1.2); $('l' + (i + 1)).textContent = typed(s, k) + (k > 0 && k < 1 ? '▌' : ''); });
-    // the dot breathes on a fixed clock, so it is the same at every render of the same t
-    const b = 1 + 0.06 * Math.sin(t * Math.PI * 1.5);
-    $('dot').style.transform = `scale(${b * out(prog(t, 0, 0.6))})`;
+    // the dot pops in, then holds: once a thing has landed, its transform must stop changing, or its edges get
+    // re-rasterised a little differently every frame and the video shows a shimmer where nothing should move
+    $('dot').style.transform = `scale(${out(prog(t, 0, 0.6))})`;
     $('end').style.opacity = prog(t, 6.5, 7.0);
   }
 

package/templates/dom/gitignore

@@ -4,3 +4,4 @@ audio/events.json
 audio/mix.wav
 audio/mix-raw.wav
 audio/vo/resp.json
+stability/

package/templates/guide/gitignore

@@ -5,3 +5,4 @@ audio/events.json
 audio/mix.wav
 audio/mix-raw.wav
 audio/vo/resp.json
+stability/