@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/compose/probe.js

@@ -0,0 +1,160 @@
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { launch } from "../verify/browser.js";
+import { serveDir } from "../verify/serve.js";
+import { planTour, readDeclared } from "../reel/tour.js";
+import { BOOT_FN, GAME_BOOT_MAX_MS, GAME_BOOT_MS } from "./page.js";
+export const AUTO_EVERY_S = 0.25;
+export function autoInputs(declared, checked, seconds) {
+    const tour = planTour({ ...declared, views: [] }, checked, Math.max(1, Math.round(seconds * 4)), 4);
+    const out = [];
+    if (tour.inputs.length) {
+        let n = 0;
+        for (let at = 0.2; at < seconds - 0.15; at += AUTO_EVERY_S, n++) {
+            const name = tour.inputs[n % tour.inputs.length];
+            out.push(tour.driven === 'verbs' ? { at: Math.round(at * 1000) / 1000, verb: name } : { at: Math.round(at * 1000) / 1000, key: name, hold: 0.12 });
+        }
+    }
+    return { inputs: out, driven: tour.driven, skipped: tour.skipped };
+}
+const PROBE_JS = `async (o) => {
+  const w = window, c = w.__FPX_STEP_CLOCK__;
+  if (!c) return { clock: false };
+  const boot = await (${BOOT_FN})(w, o);
+  const hasView = !o.view || !!(w.__FPX_VIEWS__ && w.__FPX_VIEWS__[o.view]);
+  if (o.view && hasView) { try { w.__FPX_VIEWS__[o.view].enter(); } catch (e) { /* the render will say */ } }
+  const before = c.report().game_frames;
+  await c.advance(1000);
+  const r = c.report();
+  return { clock: true, hasView, ran: r.game_frames - before, errors: r.errors, boot };
+}`;
+async function boxesOf(browser, url, c) {
+    const out = new Map();
+    const ctx = await browser.newContext({ viewport: { width: c.width, height: c.height }, deviceScaleFactor: 1 });
+    try {
+        await ctx.route('**/fpx/game.js', (r) => r.fulfill({ status: 200, contentType: 'text/javascript', body: '' }));
+        await ctx.route((u) => /\/game\/index\.html/.test(u.pathname), (r) => r.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html>' }));
+        const page = await ctx.newPage();
+        await page.addInitScript('window.__hyperframes = { registerFrameSource() { return () => {}; }, getVariables() { return {}; } };');
+        await page.goto(url + 'index.html', { waitUntil: 'load', timeout: 30_000 }).catch(() => { });
+        for (const g of c.games) {
+            const b = await page.evaluate((id) => { const el = document.getElementById(id); if (!el)
+                return null; const r = el.getBoundingClientRect(); return { width: Math.round(r.width), height: Math.round(r.height) }; }, g.id).catch(() => null);
+            if (b && b.width >= 16 && b.height >= 16)
+                out.set(g.id, b);
+        }
+    }
+    finally {
+        await ctx.close().catch(() => { });
+    }
+    return out;
+}
+async function probeOne(browser, url, g, box) {
+    const ctx = await browser.newContext({ viewport: box, deviceScaleFactor: 1 });
+    const errors = [];
+    try {
+        const page = await ctx.newPage();
+        page.on('pageerror', (e) => { if (errors.length < 6)
+            errors.push(String(e.message).slice(0, 200)); });
+        await page.goto(url + 'game/index.html', { waitUntil: 'load', timeout: 60_000 });
+        const r = await page.evaluate(`(${PROBE_JS})(${JSON.stringify({ view: g.view, boot: GAME_BOOT_MS, max: GAME_BOOT_MAX_MS })})`);
+        const declared = await readDeclared(page);
+        if (!r?.clock)
+            return { id: g.id, box, seekable: false, why: 'the staged game has no held clock', declared, gameFrames: 0, missingView: false, errors };
+        const seekable = r.ran > 0 && r.hasView;
+        const why = !r.hasView ? `it declares no view "${g.view}"` : r.ran > 0
+            ? `its loop ran ${r.ran} frames in one held second: the composition's clock drives it`
+            : 'its loop ran no frames on the held clock (it runs on AudioContext time, a Worker or new Date()), so it is filmed instead';
+        return { id: g.id, box, seekable, why, declared, gameFrames: r.ran ?? 0, missingView: !r.hasView, errors: [...errors, ...(r.errors ?? [])] };
+    }
+    finally {
+        await ctx.close().catch(() => { });
+    }
+}
+export async function openProbes(stageDir) {
+    const served = await serveDir(stageDir);
+    let browser;
+    let launches = 0;
+    const get = async () => { if (!browser) {
+        browser = (await launch(false)).browser;
+        launches++;
+    } return browser; };
+    return {
+        async probe(c) {
+            if (!c.games.length)
+                return [];
+            const b = await get();
+            const boxes = await boxesOf(b, served.url, c);
+            const out = [];
+            for (const g of c.games)
+                out.push(await probeOne(b, served.url, g, boxes.get(g.id) ?? { width: c.width, height: c.height }));
+            return out;
+        },
+        browser: get,
+        get launches() { return launches; },
+        async close() {
+            await browser?.close().catch(() => { });
+            await served.close();
+        },
+    };
+}
+export async function probeGames(stageDir, c) {
+    if (!c.games.length)
+        return [];
+    const s = await openProbes(stageDir);
+    try {
+        return await s.probe(c);
+    }
+    finally {
+        await s.close();
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
+async function press(page, i) {
+    if (i.verb)
+        await page.evaluate((n) => { try {
+            window.__FPX_VERBS__[n]();
+        }
+        catch { } }, i.verb).catch(() => { });
+    else if (i.key)
+        await page.keyboard.press(i.key, { delay: Math.round((i.hold ?? 0.08) * 1000) }).catch(() => { });
+    else if (i.tap) {
+        const v = page.viewportSize();
+        if (v)
+            await page.mouse.click(i.tap[0] * v.width, i.tap[1] * v.height).catch(() => { });
+    }
+}
+export async function filmFrames(stageDir, g, box, inputs, fps, seconds, out) {
+    await rm(out, { recursive: true, force: true });
+    await mkdir(out, { recursive: true });
+    const served = await serveDir(stageDir);
+    let browser;
+    try {
+        browser = (await launch(false)).browser;
+        const ctx = await browser.newContext({ viewport: box, deviceScaleFactor: 1 });
+        const page = await ctx.newPage();
+        await page.goto(served.url + 'game/index.html?fpx_free=1', { waitUntil: 'load', timeout: 60_000 });
+        await sleep(GAME_BOOT_MS);
+        if (g.view)
+            await page.evaluate((v) => { try {
+                window.__FPX_VIEWS__[v].enter();
+            }
+            catch { } }, g.view).catch(() => { });
+        await sleep(g.lead * 1000);
+        const total = Math.max(1, Math.round(seconds * fps));
+        const queue = [...inputs].sort((a, b) => a.at - b.at);
+        const started = Date.now();
+        for (let f = 0; f < total; f++) {
+            const due = started + (f * 1000) / fps;
+            await sleep(due - Date.now());
+            while (queue.length && queue[0].at * 1000 <= Date.now() - started)
+                await press(page, queue.shift());
+            await writeFile(join(out, `f${String(f).padStart(4, '0')}.png`), await page.screenshot({ type: 'png' }));
+        }
+        return total;
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        await served.close();
+    }
+}

package/dist/compose/run.js

@@ -0,0 +1,170 @@
+import { cp, mkdir, readFile, rm, stat, writeFile, copyFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { checkedVerbs } from "../reel/tour.js";
+import { COMPOSE_ASPECTS, injectBridge, problemsOf, readComposition, resize, resolveGame, swapToFrames, timelineOf, } from "./contract.js";
+import { BRIDGE_JS, clockScript, injectClock } from "./page.js";
+import { autoInputs, filmFrames, openProbes } from "./probe.js";
+import { HYPERFRAMES_VERSION, hyperframesCommand, hyperframesEnv, lintArgs, lintFindings, renderArgs, runHyperframes, } from "./hyperframes.js";
+import { contactSheet } from "./sheet.js";
+export const COMPOSE_SEED = 1;
+export const shown = (p) => { const r = relative(process.cwd(), p); return r && !r.startsWith('..') ? r : p; };
+export function prepare(file, html, gameDir, o = {}) {
+    const first = readComposition(html);
+    if (typeof first === 'string')
+        return first;
+    if (o.aspect || o.seconds)
+        html = resize(html, { ...(o.aspect ? { width: COMPOSE_ASPECTS[o.aspect][0], height: COMPOSE_ASPECTS[o.aspect][1] } : {}), ...(o.seconds ? { duration: o.seconds } : {}) });
+    const comp = readComposition(html);
+    const exists = (f) => existsSync(join(dirname(file), f)) || existsSync(join(gameDir, f));
+    const problems = problemsOf(comp, html, exists, existsSync(join(gameDir, 'dist', 'index.html')));
+    return { file, name: basename(file).replace(/\.html?$/i, ''), html, comp, problems };
+}
+export async function stageBase(work, gameDir, withGame) {
+    await rm(work, { recursive: true, force: true });
+    await mkdir(join(work, 'fpx'), { recursive: true });
+    if (!withGame)
+        return;
+    await cp(join(gameDir, 'dist'), join(work, 'game'), { recursive: true });
+    const page = join(work, 'game', 'index.html');
+    await writeFile(page, injectClock(await readFile(page, 'utf8')));
+    await writeFile(join(work, 'fpx', 'clock.js'), clockScript(COMPOSE_SEED));
+    await writeFile(join(work, 'fpx', 'game.js'), BRIDGE_JS);
+}
+export async function stagePage(work, p, gameDir) {
+    for (const f of p.comp.files) {
+        const from = existsSync(join(dirname(p.file), f)) ? join(dirname(p.file), f) : join(gameDir, f);
+        await mkdir(dirname(join(work, f)), { recursive: true });
+        await copyFile(from, join(work, f));
+    }
+    await writeFile(join(work, 'index.html'), injectBridge(p.html));
+}
+export async function shared(gameDir, m, work) {
+    return {
+        gameDir, m, env: hyperframesEnv(process.env, m.browser), command: hyperframesCommand(), probes: await openProbes(work),
+        manifest: await readFile(join(gameDir, 'funpixel.json'), 'utf8').then(JSON.parse).catch(() => ({})),
+    };
+}
+export async function renderStaged(p, j, s, u, say) {
+    const { comp, problems } = p;
+    let html = p.html;
+    const base = { file: p.file, name: p.name, comp, problems, record: j.record };
+    const work = j.work;
+    const games = [];
+    if (comp.games.length) {
+        let probes;
+        try {
+            probes = await s.probes.probe(comp);
+        }
+        catch (e) {
+            say(() => u.item('not_observed', `the game could not be probed: ${String(e.message).split('\n')[0]}`));
+            return { ...base, verdict: 'not_observed' };
+        }
+        for (const g of comp.games) {
+            const pr = probes.find((x) => x.id === g.id);
+            if (pr.missingView) {
+                const views = pr.declared.views.map((v) => v.name).join(', ') || 'none';
+                problems.push({ level: 'error', says: `#${g.id}: the game has no view "${g.view}"`, fix: `data-fpx-view is one of: ${views}` });
+                say(() => u.item('fail', `#${g.id}: the game has no view "${g.view}"`, `data-fpx-view is one of: ${views}`));
+                return { ...base, verdict: 'fail' };
+            }
+            let inputs = g.inputs === 'auto' || g.inputs === null ? [] : g.inputs;
+            let driven;
+            if (g.inputs === 'auto') {
+                const a = autoInputs(pr.declared, checkedVerbs(s.manifest.checks), g.duration ?? comp.duration);
+                inputs = a.inputs;
+                driven = a.driven;
+            }
+            html = resolveGame(html, g.id, { inputs });
+            if (pr.seekable) {
+                games.push({ id: g.id, mode: 'live', why: pr.why, driven, inputs: inputs.length, box: pr.box });
+            }
+            else {
+                const dirRel = `frames/${g.id}`;
+                const count = await filmFrames(work, g, pr.box, inputs, j.fps, g.duration ?? comp.duration, join(work, dirRel));
+                html = swapToFrames(html, g.id, { dir: dirRel, fps: j.fps, count });
+                games.push({ id: g.id, mode: 'frames', why: pr.why, driven, inputs: inputs.length, box: pr.box });
+            }
+            say(() => u.item(pr.seekable ? 'pass' : 'warn', `#${g.id} (${pr.box.width}x${pr.box.height}): ${pr.why}`, driven ? `${driven === 'passive' ? 'nothing to press: it plays what it does on its own' : `${inputs.length} ${driven === 'verbs' ? 'verb' : 'key'} presses from its own ${driven}`}` : undefined));
+        }
+        await writeFile(join(work, 'index.html'), injectBridge(html));
+    }
+    const lint = await runHyperframes(lintArgs(work), { cwd: work, env: s.env, timeoutMs: 300_000, command: s.command });
+    const found = lintFindings(lint.out);
+    if (found === null) {
+        const why = `HyperFrames ${HYPERFRAMES_VERSION} did not run: ${lint.out.trim().split('\n').slice(-2).join(' ').slice(0, 300)}`;
+        say(() => u.error(why, s.command.via === 'npx' ? `it is fetched with npx on first use: check the network, or npm i hyperframes@${HYPERFRAMES_VERSION} beside funtools` : undefined));
+        return { ...base, verdict: 'error', error: why, games, work };
+    }
+    const findings = found;
+    const lintErrors = findings.filter((f) => f.severity === 'error');
+    say(() => {
+        for (const f of lintErrors)
+            u.item('fail', `HyperFrames lint ${f.code}: ${f.message.split('. ')[0]}`, f.fix || undefined);
+        const kinds = new Map();
+        for (const f of findings.filter((x) => x.severity === 'warning'))
+            kinds.set(f.code, [...(kinds.get(f.code) ?? []), f]);
+        for (const [code, list] of kinds)
+            u.item('note', `HyperFrames lint ${code} ×${list.length}: ${list[0].message.split('. ')[0]}`);
+    });
+    if (lintErrors.length)
+        return { ...base, verdict: 'fail', findings, games, work };
+    if (j.check) {
+        say(() => u.summary('pass', `ready to render (HyperFrames ${HYPERFRAMES_VERSION}, staged in ${shown(work)})`));
+        return { ...base, verdict: 'pass', findings, games, work };
+    }
+    await mkdir(dirname(j.out), { recursive: true });
+    const started = Date.now();
+    const prog = (() => { let p = null; say(() => { p = u.progress(); }); return p; })();
+    let lastPct = -1;
+    const r = await runHyperframes(renderArgs({ dir: work, out: j.out, fps: j.fps, quality: j.quality, workers: games.some((g) => g.mode === 'live') ? 1 : 'auto', software: j.software }), {
+        cwd: work, env: s.env, timeoutMs: 1_800_000, command: s.command,
+        onLine: (l) => {
+            const mm = /^@hf-progress (\{.*\})$/.exec(l.trim());
+            if (!mm || !prog)
+                return;
+            try {
+                const x = JSON.parse(mm[1]);
+                if (x.pct !== lastPct) {
+                    lastPct = x.pct;
+                    prog.update(`rendering ${x.code} ${x.pct}%`);
+                }
+            }
+            catch { }
+        },
+    });
+    if (r.code !== 0 || !existsSync(j.out)) {
+        prog?.done('fail', 'the render failed');
+        const tail = r.out.trim().split('\n').filter((l) => !l.startsWith('@hf-progress')).slice(-4).join(' ').slice(0, 600);
+        say(() => u.error(`HyperFrames could not render: ${tail}`, `the staged project is ${shown(work)}: npx hyperframes@${HYPERFRAMES_VERSION} preview ${shown(work)} shows it`));
+        return { ...base, verdict: 'error', error: tail, findings, games, work };
+    }
+    prog?.done('pass', `rendered in ${Math.round((Date.now() - started) / 1000)} s`);
+    const sheet = j.out.replace(/\.mp4$/i, '') + '.sheet.jpg';
+    const looked = await contactSheet(j.out, sheet, {
+        seconds: comp.duration, fps: j.fps, wide: comp.width >= comp.height, work,
+        games: comp.games.filter((g) => games.find((x) => x.id === g.id)?.mode === 'live').map((g) => ({ id: g.id, start: g.start, end: g.start + (g.duration ?? comp.duration) })),
+    });
+    const failed = looked.checks.some((c) => c.state === 'fail');
+    const bytes = (await stat(j.out)).size;
+    return {
+        ...base, verdict: failed ? 'fail' : 'pass', findings, games, work,
+        video: j.out, bytes, sheet: looked.sheet, times: looked.times, checks: looked.checks, ms: Date.now() - started, fps: j.fps, quality: j.quality,
+    };
+}
+export function recordOf(d) {
+    return {
+        verdict: d.verdict, composition: d.file, name: d.name, renderer: { name: 'hyperframes', version: HYPERFRAMES_VERSION },
+        size: { width: d.comp.width, height: d.comp.height, aspect: d.comp.aspect }, seconds: d.comp.duration, fps: d.fps ?? null, quality: d.quality ?? null,
+        video: d.video ?? null, bytes: d.bytes ?? null, sheet: d.sheet ?? null, sheet_times: d.times ?? [], staged: d.work ?? null,
+        games: d.games ?? [], timeline: timelineOf(d.comp), checks: d.checks ?? [], problems: d.problems, lint: d.findings ?? [], ms: d.ms ?? null,
+        ...(d.error ? { error: d.error } : {}),
+    };
+}
+export async function writeRecord(d) {
+    const at = d.record ?? (d.work ? join(dirname(d.work), `${d.name}.json`) : null);
+    if (!at)
+        return;
+    await mkdir(dirname(at), { recursive: true });
+    await writeFile(at, JSON.stringify(recordOf(d), null, 2) + '\n');
+}

package/dist/compose/sheet.js

@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { decodePng } from "../look/png.js";
+import { BLANK_SHARE, frameStats, meanDiff } from "../motion/checks.js";
+export const SHEET = { cols: 4, rows: 3, cell: 480 };
+export const SHEET_FRAMES = SHEET.cols * SHEET.rows;
+export const STILL_DIFF = 0.004;
+export function sampleTimes(seconds, n = SHEET_FRAMES) {
+    return Array.from({ length: n }, (_, i) => Math.round(((i + 0.5) * seconds / n) * 1000) / 1000);
+}
+export const sampleFrames = (times, fps) => times.map((t) => Math.round(t * fps));
+const selectOf = (frames) => `select='${frames.map((n) => `eq(n\\,${n})`).join('+')}'`;
+export function sheetArgs(video, out, frames, wide) {
+    const scale = wide ? `scale=${SHEET.cell}:-2` : `scale=-2:${SHEET.cell}`;
+    return ['-hide_banner', '-loglevel', 'error', '-y', '-i', video,
+        '-vf', `${selectOf(frames)},${scale},tile=${SHEET.cols}x${SHEET.rows}:padding=6:margin=6:color=0x111111`, '-fps_mode', 'vfr', '-frames:v', '1', '-q:v', '4', out];
+}
+export function framesArgs(video, dir, frames) {
+    return ['-hide_banner', '-loglevel', 'error', '-y', '-i', video,
+        '-vf', `${selectOf(frames)},scale=240:-2`, '-fps_mode', 'vfr', '-frames:v', String(frames.length), join(dir, 's%02d.png')];
+}
+export function probeVideo(video) {
+    const r = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration:stream=codec_type,width,height', '-of', 'json', video], { encoding: 'utf8' });
+    try {
+        const j = JSON.parse(r.stdout);
+        const v = (j.streams ?? []).find((s) => s.codec_type === 'video');
+        return { seconds: Number(j.format?.duration) || null, audio: (j.streams ?? []).some((s) => s.codec_type === 'audio'), width: v?.width ?? null, height: v?.height ?? null };
+    }
+    catch {
+        return { seconds: null, audio: false, width: null, height: null };
+    }
+}
+export function checksOf(o) {
+    const out = [];
+    const frame = 1 / o.fps;
+    if (o.probed.seconds === null)
+        out.push({ id: 'length', state: 'not_observed', says: 'ffprobe could not read the video' });
+    else {
+        const off = Math.abs(o.probed.seconds - o.seconds);
+        out.push(off <= frame * 1.5 + 0.05
+            ? { id: 'length', state: 'pass', says: `${o.probed.seconds.toFixed(2)} s, as composed` }
+            : { id: 'length', state: 'fail', says: `${o.probed.seconds.toFixed(2)} s, the composition says ${o.seconds} s` });
+    }
+    const judged = o.times.map((t, i) => ({ t, s: o.stats[i] })).filter((x) => x.s && x.t > 0.5 && x.t < o.seconds - 0.5);
+    if (!judged.length)
+        out.push({ id: 'blank', state: 'not_observed', says: 'no frame could be read' });
+    else {
+        const blank = judged.filter((x) => x.s.share >= BLANK_SHARE);
+        out.push(blank.length
+            ? { id: 'blank', state: 'fail', says: `nearly one colour at ${blank.map((x) => `${x.t} s`).join(', ')}` }
+            : { id: 'blank', state: 'pass', says: `none of ${judged.length} sampled frames is blank` });
+    }
+    for (const g of o.games) {
+        const inside = o.times.map((t, i) => ({ t, s: o.stats[i] })).filter((x) => x.s && x.t >= g.start && x.t < g.end);
+        if (inside.length < 2) {
+            out.push({ id: 'game', state: 'not_observed', says: `#${g.id}: fewer than two sampled frames fall in the clip` });
+            continue;
+        }
+        let moved = 0;
+        for (let i = 1; i < inside.length; i++)
+            moved = Math.max(moved, meanDiff(inside[i - 1].s, inside[i].s));
+        out.push(moved > STILL_DIFF
+            ? { id: 'game', state: 'pass', says: `#${g.id} moves across its ${inside.length} sampled frames` }
+            : { id: 'game', state: 'fail', says: `#${g.id} is the same picture in all ${inside.length} sampled frames: stuck on a loading or title screen, or not driven (data-fpx-view, data-fpx-inputs)` });
+    }
+    return out;
+}
+export async function contactSheet(video, sheet, o) {
+    const times = sampleTimes(o.seconds);
+    const frames = sampleFrames(times, o.fps);
+    const s = spawnSync('ffmpeg', sheetArgs(video, sheet, frames, o.wide), { encoding: 'utf8' });
+    const dir = join(o.work, 'samples');
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    spawnSync('ffmpeg', framesArgs(video, dir, frames), { encoding: 'utf8' });
+    const files = readdirSync(dir).filter((f) => f.endsWith('.png')).sort();
+    const stats = times.map((_, i) => {
+        const f = files[i];
+        if (!f)
+            return null;
+        try {
+            return frameStats(decodePng(readFileSync(join(dir, f))), 2);
+        }
+        catch {
+            return null;
+        }
+    });
+    const checks = checksOf({ seconds: o.seconds, fps: o.fps, probed: probeVideo(video), times, stats, games: o.games });
+    return { sheet: s.status === 0 ? sheet : null, times, checks, ...(s.status === 0 ? {} : { error: (s.stderr || '').trim().split('\n').slice(-1)[0] }) };
+}