multiplane 0.0.0-stage → 0.3.0

package/src/hosted.mjs

@@ -0,0 +1,134 @@
+import path from 'node:path';
+import { mkdir, readFile, writeFile, rename, open, stat, unlink } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { userHome } from './platform.mjs';
+import { processCreatedAt } from './process-identity.mjs';
+import { errorCodes, MultiplaneError } from './errors.mjs';
+
+const schema = 'multiplane/1';
+export const hostedBase = (jobId, home = userHome()) => path.join(home, 'hosted', jobId);
+async function json(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT' || error instanceof SyntaxError) return null; throw error; }
+}
+async function exists(file) { try { await stat(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; } }
+async function move(from, to) {
+  try { await rename(from, to); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function hostedAvailable(command, options, env = process.env) {
+  if (!['render', 'stills', 'verify'].includes(command) || !options._hostedCLI || options.hosted !== true
+    || options['no-hosted'] || options['hosted-executor'] || env.MULTIPLANE_HOSTED === '0') return false;
+  try {
+    const app = await json(path.join(userHome(env), 'app.json'));
+    return app?.schema === schema && app.acceptsHosted === true && typeof app.version === 'string'
+      && typeof app.createdAt === 'string' && app.createdAt === await processCreatedAt(app.pid);
+  } catch { return false; }
+}
+
+export function hostedEnvironment(env) {
+  const allowed = /^(PATH|MULTIPLANE_.*|HTTPS?_PROXY|ALL_PROXY|NO_PROXY|TEMP|TMP|TMPDIR|HOME|USERPROFILE|APPDATA|LOCALAPPDATA|SystemRoot|ComSpec|PATHEXT|LANG|LC_.*)$/i;
+  const secret = /TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|BEARER|COOKIE|SESSION|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY/i;
+  return Object.fromEntries(Object.entries(env).filter(([key, value]) => {
+    if (value === undefined || !allowed.test(key) || secret.test(key)) return false;
+    // Do not persist proxy passwords or tokens carried in proxy URLs.
+    if (/PROXY$/i.test(key) && !/^NO_PROXY$/i.test(key)) {
+      try { const url = new URL(value); if (url.username || url.password || url.search || url.hash) return false; }
+      catch { return false; }
+    }
+    return true;
+  }));
+}
+
+export async function handoff(request, { home = userHome(), timeout = 5000, startTimeout = 15000,
+  interval = 100, announce = message => process.stderr.write(message + '\n') } = {}) {
+  const base = hostedBase(request.jobId, home);
+  try {
+    await mkdir(path.dirname(base), { recursive: true });
+    await writeFile(base + '.tmp', JSON.stringify(request) + '\n', { flag: 'wx', mode: 0o600 });
+    await rename(base + '.tmp', base + '.request.json');
+  } catch {
+    await unlink(base + '.tmp').catch(() => {});
+    return { reason: 'The hosted request could not be published.' };
+  }
+  const deadline = performance.now() + timeout;
+  let accepted = false, startDeadline = Infinity;
+  for (;;) {
+    if (await exists(base + '.rejected.json')) {
+      const rejected = await json(base + '.rejected.json');
+      return { reason: typeof rejected?.reason === 'string' ? rejected.reason : 'The app rejected the request.' };
+    }
+    const running = await exists(base + '.running.json');
+    const claimed = await exists(base + '.claimed.json');
+    const status = await json(path.join(request.jobDir, 'status.json'));
+    const queued = status?.state === 'queued';
+    if (!accepted && (claimed || running || status?.result)) {
+      accepted = true; startDeadline = performance.now() + startTimeout;
+    }
+    if (running || status?.result || (accepted && queued)) {
+      announce('Job ' + request.jobId + ' has been handed to Multiplane'
+        + (queued ? (Number.isSafeInteger(status.queuePosition) && status.queuePosition > 0 ? ' (queued; #' + status.queuePosition + ')' : ' (queued; position unavailable)') : '') + '. Closing this session will not interrupt it.');
+      return { hosted: true };
+    }
+    if (accepted && performance.now() >= startDeadline && status?.state !== 'queued') {
+      if (await move(base + '.claimed.json', base + '.withdrawn.json')) return { reason: 'The app did not start the job within 15 seconds.' };
+    }
+    if (!accepted && performance.now() >= deadline) {
+      if (await move(base + '.request.json', base + '.withdrawn.json')) return { reason: 'The app did not claim the job within 5 seconds.' };
+    }
+    await delay(interval);
+  }
+}
+
+// Claim before loading config, creating status, linting or opening output files.
+export async function claimExecutor(jobDir, command) {
+  try {
+    if (!path.isAbsolute(jobDir) || !['render', 'stills', 'verify'].includes(command)) return false;
+    const jobId = path.basename(jobDir), base = hostedBase(jobId);
+    const request = await json(base + '.claimed.json');
+    if (request?.schema !== schema || request.jobId !== jobId || request.command !== command
+      || path.resolve(request.jobDir ?? '') !== path.resolve(jobDir)) return false;
+    return await move(base + '.claimed.json', base + '.running.json');
+  } catch { return false; }
+}
+
+export const resultExitCode = result => result.ok ? 0 : errorCodes[result.code]?.exitCode ?? 4;
+
+// Keep bytes intact across partial writes and UTF-8 boundaries. Only complete lines
+// are published, so timeout diagnostics cannot splice into a partial JSON record.
+export async function followJob(directory, { timeout = Infinity, onBytes, onEvent, interval = 100 } = {}) {
+  const deadline = performance.now() + timeout * 1000;
+  let offset = 0, pending = Buffer.alloc(0);
+  for (;;) {
+    let handle;
+    try {
+      handle = await open(path.join(directory, 'events.jsonl'), 'r');
+      for (;;) {
+        const buffer = Buffer.alloc(64 * 1024);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+        if (!bytesRead) break;
+        offset += bytesRead;
+        pending = Buffer.concat([pending, buffer.subarray(0, bytesRead)]);
+        let end;
+        while ((end = pending.indexOf(10)) !== -1) {
+          const line = pending.subarray(0, end + 1); pending = pending.subarray(end + 1);
+          const event = JSON.parse(line.toString('utf8'));
+          await onBytes?.(line); onEvent?.(event);
+          if (event.type === 'result') return event;
+        }
+      }
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    finally { await handle?.close(); }
+    const status = await json(path.join(directory, 'status.json'));
+    if (status?.schema !== schema || !Number.isSafeInteger(status.pid) || status.pid <= 0
+      || typeof status.state !== 'string') throw new MultiplaneError('job_not_found');
+    // A result is committed to the event log before status; read the next poll.
+    if (!status.result && status.state === 'running') {
+      try { process.kill(status.pid, 0); }
+      catch (error) { if (error.code === 'ESRCH') throw new MultiplaneError('internal_error', 'Job process exited without a result.'); }
+    }
+    if (performance.now() >= deadline) throw new MultiplaneError('wait_timeout');
+    await delay(interval);
+  }
+}

package/src/index.mjs

@@ -0,0 +1,14 @@
+export { renderShot } from './render.mjs';
+export { stillsShot } from './stills.mjs';
+export { verifyShot } from './verify.mjs';
+export { openShot } from './capture.mjs';
+export { inspectShot } from './inspect.mjs';
+export { createPostCapture } from './post.mjs';
+export { createRenderPool } from './render-pool.mjs';
+export { MultiplaneError, errorCodes } from './errors.mjs';
+export { doctor } from './doctor.mjs';
+export { statusJob, cancelJob, waitJob } from './jobs.mjs';
+
+import { runCommand } from './events.mjs';
+import { checkLint } from './lint.mjs';
+export const lintShot = (shot, options = {}) => runCommand('lint', shot, options, events => checkLint(shot, events.options, events), false);

package/src/inspect.mjs

@@ -0,0 +1,20 @@
+import path from 'node:path';
+import { openShot, number } from './capture.mjs';
+import { runCommand } from './events.mjs';
+import { frameRate } from './frame-rate.mjs';
+import { invalidOption } from './errors.mjs';
+
+export async function inspectShot(shot, options = {}) {
+  return runCommand('inspect', shot, options, async events => {
+    const capture = await openShot(shot, 1, events.options);
+    try {
+      const { duration, width, height, cuts, post, hasBlurAt, meta } = capture;
+      const fps = number(events.options.fps ?? capture.fps, '--fps', { positive: true });
+      frameRate(fps);
+      const frames = Math.ceil(duration * fps - 1e-9);
+      if (!frames) throw invalidOption('--from', 'Range contains no frames.');
+      return { shot: path.resolve(events.options.root, shot), duration, fps, frames,
+        stage: { width, height }, cuts, post, hasBlurAt, meta };
+    } finally { await capture.close(); }
+  }, false);
+}

package/src/jobs.mjs

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { setTimeout } from 'node:timers/promises';
+import { jobDirectory, runCommand } from './events.mjs';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+import { number } from './capture.mjs';
+import { followJob } from './hosted.mjs';
+import { loadUserConfig } from './user-home.mjs';
+
+const resolveJob = (target, options) => path.isAbsolute(target) || /[\\/]/.test(target) ? path.resolve(target) : path.join(jobDirectory(options), target);
+export async function readStatus(target, options = {}) {
+  let status;
+  try { status = JSON.parse(await readFile(path.join(resolveJob(target, options), 'status.json'), 'utf8')); }
+  catch (cause) { throw new MultiplaneError('job_not_found'); }
+  if (!status || status.schema !== 'multiplane/1' || !Number.isSafeInteger(status.pid) || status.pid <= 0
+    || typeof status.state !== 'string') throw new MultiplaneError('job_not_found');
+  if (status.state === 'running') {
+    try { process.kill(status.pid, 0); }
+    catch (error) {
+      if (error.code === 'ESRCH') {
+        // Report a vanished process as failed/internal_error without changing the status file.
+        status = { ...status, state: 'failed', result: { schema: 'multiplane/1', type: 'result', command: status.command,
+          ts: new Date().toISOString(), ok: false, code: 'internal_error', message: 'Job process exited without a result.',
+          artifacts: [], elapsedMs: Math.max(0, Date.now() - Date.parse(status.startedAt)), jobId: status.jobId, data: {} } };
+      }
+    }
+  }
+  return status;
+}
+export const statusJob = (target, options = {}) => runCommand('status', null, options, events => readStatus(target, events.options), false);
+const active = status => !['succeeded', 'failed', 'cancelled'].includes(status.state);
+export async function waitJob(target, options = {}) {
+  const timeout = options.timeout === undefined ? Infinity : Number(options.timeout);
+  if (options.timeout !== undefined && (!String(options.timeout).trim() || !Number.isFinite(timeout) || timeout < 0)) throw invalidOption('--timeout', 'Invalid value for --timeout.');
+  const configured = loadUserConfig('wait', options).options;
+  return followJob(resolveJob(target, configured), { timeout, onBytes: options.onBytes, onEvent: options.onEvent });
+}
+export const cancelJob = (target, options = {}) => runCommand('cancel', null, { wait: 30, ...options }, async events => {
+  options = events.options;
+  const wait = number(options.wait ?? 30, '--wait');
+  let status = await readStatus(target, options);
+  if (!active(status)) return status;
+  await writeFile(path.join(resolveJob(target, options), 'stop'), '');
+  const deadline = performance.now() + wait * 1000;
+  while (active(status) && performance.now() < deadline) {
+    await setTimeout(100);
+    status = await readStatus(target, options);
+  }
+  if (active(status)) throw new MultiplaneError('cancel_timeout', 'Timed out waiting for job cancellation.', { result: { data: status } });
+  return status;
+}, false);

package/src/lint.mjs

@@ -0,0 +1,248 @@
+import { normalizeResourcePath, isInsideResourceRoot } from './resource-path.mjs';
+import path from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+import { parse as parseJS } from 'acorn';
+import { parse as parseHTML } from 'parse5';
+import postcss from 'postcss';
+import values from 'postcss-value-parser';
+import { MultiplaneError } from './errors.mjs';
+
+const rules = {
+  wall_clock: ['error', 'Wall-clock time is nondeterministic.', 'Calculate time from the render(t) argument.'],
+  unseeded_random: ['error', 'Unseeded randomness is nondeterministic.', 'Use a seeded random generator with a fixed seed.'],
+  css_animation: ['error', 'An autonomous CSS animation or transition is used.', 'Set animation and transition to none and assign styles from render(t).'],
+  web_animations: ['error', 'The Web Animations timeline is used.', 'Calculate and assign each animated property in render(t).'],
+  timer_driven: ['warning', 'A timer can change the frame independently of t.', 'Move visual updates into render(t).'],
+  media_playback: ['error', 'Autonomous media playback is used.', 'Use a still image or predecoded frame selected by t.'],
+  animated_image: ['warning', 'An animated image may advance independently of t.', 'Replace it with still frames selected by t.'],
+  remote_resource: ['error', 'A resource is loaded from the network.', 'Download the resource and reference a local file inside the resource root.'],
+  resource_missing: ['error', 'A local resource is missing or outside the resource root.', 'Place the file inside the resource root and correct the relative URL.'],
+  stage_missing: ['error', 'The stage element is missing.', 'Add an element with id="stage".'],
+  stage_size_unfixed: ['warning', 'Fixed stage dimensions could not be found.', 'Set #stage width and height to positive px values.'],
+  shot_missing: ['error', 'The shot definition is missing.', 'Call Shot.define({...}) or assign window.SHOT.'],
+  runtime_missing: ['error', 'Shot.define is used without the runtime.', 'Include /multiplane/runtime/shot.js before defining the shot.'],
+  async_render: ['error', 'The render function is asynchronous.', 'Await resources in setup and make render(t) synchronous.'],
+  font_not_awaited: ['warning', 'Custom fonts have no explicit loading declaration.', 'Add fonts to Shot.define or await document.fonts.load in setup.'],
+  lint_directive_invalid: ['warning', 'The lint directive has no valid rule codes.', 'List rule codes after multiplane-disable-next-line.'],
+  lint_incomplete: ['warning', 'Source parsing failed.', 'Correct the source syntax to complete lint coverage.'],
+};
+const children = node => Object.values(node).flatMap(v => Array.isArray(v) ? v : [v]).filter(v => v && typeof v.type === 'string');
+const walk = (node, fn, parents = []) => { fn(node, parents); for (const child of children(node)) walk(child, fn, [...parents, node]); };
+const member = n => n?.type === 'Identifier' ? n.name : n?.type === 'MemberExpression' && !n.computed ? `${member(n.object)}.${n.property.name}` : '';
+const literal = n => n?.type === 'Literal' && typeof n.value === 'string' ? n.value : n?.type === 'TemplateLiteral' && !n.expressions.length ? n.quasis[0].value.cooked : null;
+
+export async function scanShot(shot, options = {}) {
+  const root = await normalizeResourcePath(path.resolve(options.root ?? process.cwd()));
+  const entry = path.resolve(root, shot);
+  if (!await isInsideResourceRoot(root, entry)) throw new MultiplaneError('shot_outside_root');
+  let entryReal;
+  try { entryReal = await normalizeResourcePath(entry); if (!(await stat(entryReal)).isFile()) throw Error(); }
+  catch { throw new MultiplaneError('shot_not_found'); }
+  if (!await isInsideResourceRoot(root, entryReal)) throw new MultiplaneError('shot_outside_root');
+  const sources = new Map(), pending = [], findings = [], directives = new Map(), seen = new Set();
+  const state = { stage: null, width: false, height: false, shot: false, define: null, runtime: false, fonts: false, fontFace: null, fontLoad: false };
+  const location = (file, offset) => {
+    const prefix = sources.get(file).slice(0, offset), lines = prefix.split('\n');
+    return { file: path.relative(root, file).split(path.sep).join('/'), line: lines.length, column: lines.at(-1).length + 1 };
+  };
+  const add = (code, file, offset, extra = {}) => {
+    const loc = location(file, offset), [severity, message, hint] = rules[code];
+    if (findings.some(f => f.code === code && f.location.file === loc.file && f.location.line === loc.line && f.location.column === loc.column)) return;
+    findings.push({ code, severity, message, hint, location: loc, ...extra, details: { snippet: sources.get(file).split('\n')[loc.line - 1].trim().slice(0, 160), ...extra.details } });
+  };
+  const comment = (file, offset, text) => {
+    const match = /multiplane-disable-next-line\b([^\r\n]*)/.exec(text);
+    if (!match) return;
+    const codes = match[1].trim().split(/\s*,\s*/).filter(c => rules[c] && c !== 'lint_directive_invalid');
+    if (!codes.length) add('lint_directive_invalid', file, offset);
+    else {
+      const loc = location(file, offset + text.slice(0, match.index).length);
+      directives.set(`${loc.file}:${loc.line + 1}`, new Set([...(directives.get(`${loc.file}:${loc.line + 1}`) ?? []), ...codes]));
+    }
+  };
+  const resource = (url, file, offset, kind, module = false) => {
+    if (url === null) return;
+    url = url.trim();
+    if (/^(https?:)?\/\//i.test(url)) { add('remote_resource', file, offset); return; }
+    if (!url || /^(data:|blob:|#)/i.test(url)) return;
+    if ((kind === 'js' || module) && url.split(/[?#]/)[0] === '/multiplane/runtime/shot.js') state.runtime = true;
+    if (url.startsWith('/multiplane/')) return;
+    if (module && !/^[./]/.test(url)) return;
+    if (/^[a-z][\w+.-]*:/i.test(url)) return;
+    if (/\.(gif|apng)(?:[?#]|$)/i.test(url)) add('animated_image', file, offset);
+    pending.push({ url, file, offset, kind });
+  };
+  function css(text, file, base = 0, inlineStage = false) {
+    let tree;
+    try { tree = postcss.parse(text, { from: file, map: false }); }
+    catch (error) { add('lint_incomplete', file, base, { message: 'CSS parsing failed; source fragment was skipped.', details: { reason: error.message.split(/\r?\n/)[0] } }); return; }
+    tree.walk(node => {
+      const offset = base + node.source.start.offset;
+      if (node.type === 'comment') comment(file, offset, node.text);
+      if (node.type === 'atrule') {
+        if (/^(?:-\w+-)?keyframes$/i.test(node.name)) add('css_animation', file, offset);
+        if (node.name.toLowerCase() === 'font-face') state.fontFace ??= { file, offset };
+        if (node.name.toLowerCase() === 'import') {
+          const first = values(node.params).nodes.find(n => !['space', 'comment'].includes(n.type));
+          if (first?.type === 'string') resource(first.value, file, offset, 'css');
+        }
+      }
+      if (node.type === 'decl') {
+        const prop = node.prop.toLowerCase(), value = node.value.trim().toLowerCase();
+        if (['animation', 'animation-name'].includes(prop) && value.split(',').some(v => v.trim() !== 'none')) add('css_animation', file, offset);
+        if (['transition', 'transition-duration'].includes(prop)) {
+          const durations = value.match(/-?(?:\d*\.)?\d+m?s\b/g) ?? [];
+          if (durations.some(v => parseFloat(v) !== 0)) add('css_animation', file, offset);
+        }
+        if (inlineStage || (node.parent.type === 'rule' && node.parent.selector.split(',').some(s => s.trim() === '#stage'))) {
+          if (['width', 'height'].includes(prop) && /^\d+(?:\.\d+)?px$/.test(value) && parseFloat(value) > 0) state[prop] = true;
+        }
+      }
+      if (node.type === 'decl' || node.type === 'atrule') {
+        values(node.value ?? node.params).walk(v => {
+          if (v.type === 'function' && v.value.toLowerCase() === 'url') {
+            const url = v.nodes.filter(n => !['space', 'comment'].includes(n.type)).map(n => n.value).join('');
+            resource(url, file, offset, node.type === 'atrule' && node.name === 'import' ? 'css' : undefined);
+            return false;
+          }
+        });
+      }
+    });
+  }
+  function js(text, file, base = 0, module = false) {
+    let tree;
+    try { tree = parseJS(text, { ecmaVersion: 'latest', sourceType: module ? 'module' : 'script', allowAwaitOutsideFunction: true,
+      onComment: (_block, value, start) => comment(file, base + start, value) }); }
+    catch (error) { add('lint_incomplete', file, base, { message: 'JavaScript parsing failed; source fragment was skipped.', details: { reason: error.message.split(/\r?\n/)[0] } }); return; }
+    const bindings = new Map();
+    let globalShotVariable = false;
+    // Track lexical scopes so local variables named Date/Math/etc. do not match globals.
+    const isScope = n => /Function/.test(n.type) || ['Program', 'BlockStatement', 'ArrowFunctionExpression', 'CatchClause'].includes(n.type);
+    const bind = (scope, pattern) => {
+      if (!scope || !pattern) return;
+      const names = bindings.get(scope) ?? new Set(); bindings.set(scope, names);
+      if (pattern.type === 'Identifier') names.add(pattern.name);
+      else for (const c of children(pattern)) bind(scope, c);
+    };
+    walk(tree, (n, ancestors) => {
+      if (/Function/.test(n.type)) { for (const p of n.params ?? []) bind(n, p); if (n.id) bind(n.type === 'FunctionDeclaration' ? ancestors.findLast(isScope) : n, n.id); }
+      if (n.type === 'VariableDeclaration') for (const d of n.declarations) {
+        bind(ancestors.findLast(a => n.kind === 'var' ? /Function/.test(a.type) || a.type === 'Program' : isScope(a)), d.id);
+        if (!module && n.kind === 'var' && d.id.name === 'SHOT' && !ancestors.some(a => /Function/.test(a.type))) {
+          globalShotVariable = true;
+          if (d.init) state.shot = true;
+        }
+      }
+      if (n.type === 'ImportDeclaration') for (const s of n.specifiers) bind(tree, s.local);
+      if (n.type === 'ClassDeclaration') bind(ancestors.findLast(isScope), n.id);
+      if (n.type === 'CatchClause') bind(n, n.param);
+    });
+    walk(tree, (n, ancestors) => {
+      const offset = base + n.start, call = ['CallExpression', 'NewExpression'].includes(n.type);
+      const name = member(call ? n.callee : n), global = value => ![...ancestors, n].some(a => bindings.get(a)?.has(value.split('.')[0]));
+      if (call && global(name)) {
+        if (['Date.now', 'performance.now'].includes(name) || name === 'Date' && (n.type === 'CallExpression' || !n.arguments.length)) add('wall_clock', file, offset);
+        if (['Math.random', 'crypto.getRandomValues', 'crypto.randomUUID'].includes(name)) add('unseeded_random', file, offset);
+        if (['setTimeout', 'setInterval', 'requestAnimationFrame', 'requestIdleCallback'].includes(name.replace(/^(window|globalThis)\./, ''))) add('timer_driven', file, offset);
+        if (name === 'Animation' && n.type === 'NewExpression') add('web_animations', file, offset);
+        if (name === 'Audio' && n.type === 'NewExpression') add('media_playback', file, offset);
+        if (name === 'fetch') resource(literal(n.arguments[0]), file, base + (n.arguments[0]?.start ?? n.start));
+        if (name === 'FontFace') {
+          const source = literal(n.arguments[1]);
+          if (source) values(source).walk(v => { if (v.type === 'function' && v.value === 'url') resource(v.nodes.map(x => x.value).join(''), file, base + n.arguments[1].start); });
+        }
+        if (name === 'Shot.define') {
+          state.shot = true; state.define ??= { file, offset };
+          // An indirect definition may supply fonts; do not infer their absence.
+          state.fonts ||= n.arguments[0]?.type !== 'ObjectExpression' || n.arguments[0].properties.some(p => (p.key?.name ?? p.key?.value) === 'fonts' || p.type === 'SpreadElement');
+        }
+        if (name === 'document.fonts.load') state.fontLoad = true;
+      }
+      if (call && n.callee.type === 'MemberExpression' && !n.callee.computed) {
+        if (n.callee.property.name === 'animate') add('web_animations', file, offset);
+        if (n.callee.property.name === 'play') add('media_playback', file, offset);
+      }
+      if (name === 'document.timeline' && global(name)) add('web_animations', file, offset);
+      if (n.type === 'AssignmentExpression') {
+        const target = member(n.left);
+        if (['SHOT', 'window.SHOT'].includes(target) && (global(target) || target === 'SHOT' && globalShotVariable
+          && !ancestors.some(a => a.type !== 'Program' && bindings.get(a)?.has('SHOT')))) state.shot = true;
+        const value = literal(n.right);
+        if (/\.style\.(animation|transition)$/.test(target) && value !== null && value !== '') add('css_animation', file, offset);
+      }
+      if (n.type === 'ImportDeclaration' || ['ExportNamedDeclaration', 'ExportAllDeclaration'].includes(n.type) && n.source) resource(literal(n.source), file, base + n.source.start, 'js', true);
+      if (n.type === 'ImportExpression') resource(literal(n.source), file, base + n.source.start, undefined, true);
+      const render = ['Property', 'MethodDefinition'].includes(n.type) && (n.key.name ?? n.key.value) === 'render' ? n.value
+        : n.type === 'VariableDeclarator' && n.id.name === 'render' ? n.init
+        : n.type === 'FunctionDeclaration' && n.id?.name === 'render' ? n
+          : n.type === 'AssignmentExpression' && /(?:^|\.)render$/.test(member(n.left)) ? n.right : null;
+      if (render && /Function/.test(render.type)) {
+        let async = render.async;
+        walk(render.body, child => { if (child.type === 'AwaitExpression') async = true; });
+        if (async) add('async_render', file, offset);
+      }
+    });
+  }
+  async function scan(file, kind) {
+    if (seen.has(file)) return;
+    seen.add(file);
+    const text = await readFile(file, 'utf8'); sources.set(file, text);
+    if (kind === 'js') return js(text, file, 0, true);
+    if (kind === 'css') return css(text, file);
+    const tree = parseHTML(text, { sourceCodeLocationInfo: true });
+    function visit(node) {
+      const loc = node.sourceCodeLocation, attrs = Object.fromEntries((node.attrs ?? []).map(a => [a.name, a.value]));
+      if (node.nodeName === '#comment') comment(file, loc.startOffset, node.data);
+      if (loc && node.tagName) {
+        if (attrs.id === 'stage') state.stage ??= { file, offset: loc.startOffset };
+        if (['video', 'audio'].includes(node.tagName)) add('media_playback', file, loc.startOffset);
+        for (const a of node.attrs ?? []) {
+          const attrLoc = loc.attrs[a.name];
+          if (a.name === 'style') {
+            const raw = text.slice(attrLoc.startOffset, attrLoc.endOffset), match = /=\s*["']?/.exec(raw);
+            if (match) {
+              const valueStart = match.index + match[0].length;
+              css(raw.slice(valueStart).replace(/["']$/, ''), file, attrLoc.startOffset + valueStart, attrs.id === 'stage');
+            }
+          }
+          if (['src', 'href', 'poster', 'xlink:href'].includes(a.name) && !(node.tagName === 'a' && a.name === 'href')) resource(a.value, file, attrLoc.startOffset,
+            node.tagName === 'script' ? 'js' : node.tagName === 'link' && attrs.rel?.split(/\s+/).includes('stylesheet') ? 'css' : undefined);
+        }
+        if (node.tagName === 'script' && !attrs.src && (!attrs.type || /^(module|(?:text|application)\/(?:java|ecma)script)$/i.test(attrs.type))) js(text.slice(loc.startTag.endOffset, loc.endTag?.startOffset ?? loc.endOffset), file, loc.startTag.endOffset, attrs.type === 'module');
+        if (node.tagName === 'style') css(text.slice(loc.startTag.endOffset, loc.endTag?.startOffset ?? loc.endOffset), file, loc.startTag.endOffset);
+      }
+      for (const child of node.childNodes ?? []) visit(child);
+    }
+    visit(tree);
+  }
+  await scan(entryReal, 'html');
+  for (let i = 0; i < pending.length; i++) {
+    const { url, file, offset, kind } = pending[i];
+    let target;
+    try {
+      const decoded = decodeURIComponent(url.split(/[?#]/)[0]);
+      target = path.resolve(decoded.startsWith('/') ? root : path.dirname(file), decoded.replace(/^\//, ''));
+      if (!await isInsideResourceRoot(root, target)) throw Error();
+      target = await normalizeResourcePath(target);
+      if (!await isInsideResourceRoot(root, target) || !(await stat(target)).isFile()) throw Error();
+    } catch { add('resource_missing', file, offset); continue; }
+    if (kind) await scan(target, kind);
+  }
+  if (!state.stage) add('stage_missing', entryReal, 0);
+  else if (!state.width || !state.height) add('stage_size_unfixed', state.stage.file, state.stage.offset);
+  if (!state.shot) add('shot_missing', entryReal, 0);
+  if (state.define && !state.runtime) add('runtime_missing', state.define.file, state.define.offset);
+  if (state.fontFace && !state.fonts && !state.fontLoad) add('font_not_awaited', state.fontFace.file, state.fontFace.offset);
+  const visible = findings.filter(f => !directives.get(`${f.location.file}:${f.location.line}`)?.has(f.code));
+  visible.sort((a, b) => a.location.file.localeCompare(b.location.file) || a.location.line - b.location.line || a.location.column - b.location.column || a.code.localeCompare(b.code));
+  const data = { files: [...sources.keys()].map(f => path.relative(root, f).split(path.sep).join('/')), errors: visible.filter(f => f.severity === 'error').length,
+    warnings: visible.filter(f => f.severity === 'warning').length, suppressed: findings.length - visible.length };
+  return { findings: visible, data };
+}
+
+export async function checkLint(shot, options, events) {
+  const { findings, data } = await scanShot(shot, options);
+  for (const finding of findings) events.emit('finding', finding);
+  if (data.errors) throw new MultiplaneError('lint_failed', undefined, { result: { data } });
+  return data;
+}

package/src/output-alpha.mjs

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+import { stopChild } from './process.mjs';
+import { MultiplaneError } from './errors.mjs';
+
+export async function checkAlphaVideo(ffmpeg, file, format, references, width, height, events) {
+  const indices = [...references.keys()];
+  const pixels = width * height;
+  // TODO(design): Document the maximum alpha error of 2/255 for encoded frames.
+  const tolerance = 2;
+  return new Promise((resolve, reject) => {
+    const child = spawn(ffmpeg, ['-hide_banner', '-nostdin', '-loglevel', 'error',
+      ...(format === 'webm' ? ['-c:v', 'libvpx-vp9'] : []), '-i', file,
+      '-map', '0:v:0', '-vf', `select=${indices.map(i => `eq(n\\,${i})`).join('+')},alphaextract`,
+      '-fps_mode', 'passthrough', '-frames:v', String(indices.length), '-pix_fmt', 'gray', '-f', 'rawvideo', 'pipe:1'],
+    { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const unsubscribe = events?.onCancel?.(() => stopChild(child));
+    let count = 0, maxError = 0, stderr = '', overflow = false;
+    child.stdout.on('data', bytes => {
+      for (const actual of bytes) {
+        const reference = references.get(indices[Math.floor(count / pixels)]);
+        if (!reference) overflow = true;
+        else maxError = Math.max(maxError, Math.abs(actual - reference[count % pixels]));
+        count++;
+      }
+    });
+    child.stderr.on('data', bytes => { stderr = (stderr + bytes).slice(-4000); });
+    child.once('error', cause => reject(new MultiplaneError('output_invalid', 'Alpha could not be decoded.', { cause })));
+    child.once('close', code => {
+      unsubscribe?.();
+      try { events?.check(); } catch (error) { reject(error); return; }
+      if (code !== 0 || overflow || count !== pixels * indices.length || maxError > tolerance) {
+        reject(new MultiplaneError('output_invalid', 'Decoded alpha does not match the source frames.', { details: { frames: indices, maxAlphaError: maxError, tolerance, decodedBytes: count, stderr } }));
+      } else resolve({ frames: indices, maxAlphaError: maxError, tolerance });
+    });
+  });
+}

package/src/output-check.mjs

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import { readFile, rm } from 'node:fs/promises';
+import { decodeNativePNG } from './png-native.mjs';
+import { MultiplaneError } from './errors.mjs';
+import { stopChild } from './process.mjs';
+
+// Container timestamp precision (notably WebM/Matroska) makes decoded rates
+// approximate; apply the same relative tolerance to every output format.
+const FRAME_RATE_RELATIVE_TOLERANCE = 1e-4;
+
+async function probePass(ffmpeg, args, events, spawnProcess, line) {
+  events?.check?.();
+  await new Promise((resolve, reject) => {
+    const child = spawnProcess(ffmpeg, ['-hide_banner', '-nostdin', '-nostats', ...args], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] });
+    const unsubscribe = events?.onCancel?.(() => stopChild(child));
+    let buffer = '';
+    child.stderr.on('data', bytes => {
+      buffer += bytes.toString();
+      let end;
+      while ((end = buffer.indexOf('\n')) >= 0) { line(buffer.slice(0, end)); buffer = buffer.slice(end + 1); }
+      if (buffer.length > 65536) buffer = buffer.slice(-65536);
+    });
+    child.once('error', error => { unsubscribe?.(); reject(error); });
+    child.once('close', code => {
+      unsubscribe?.(); line(buffer);
+      if (code !== 0) return reject(new Error('FFmpeg probe exited with code ' + code + '.'));
+      resolve();
+    });
+  });
+  events?.check?.();
+}
+
+export async function probeVideo(ffmpeg, file, events, spawnProcess = spawn, options = {}) {
+  // Count copied video packets independently of decoding and audio scheduling.
+  let packetCount;
+  await probePass(ffmpeg, ['-i', file, '-map', '0:v:0', '-an', '-c', 'copy', '-loglevel', 'verbose', '-f', 'null', '-'], events, spawnProcess, text => {
+    const count = text.match(/Output stream #0:0 \(video\):\s*(\d+) packets muxed/);
+    if (count) packetCount = Number(count[1]);
+  });
+  if (!Number.isSafeInteger(packetCount)) throw new Error('FFmpeg packet count could not be parsed.');
+  let frames = 0, minTime = Infinity, maxTime = -Infinity, audioStart = Infinity, audioEnd = -Infinity;
+  let width, height, fps, codec, pixelFormat, timeBase;
+  let input = true, hasAudio = false;
+  const line = text => {
+    if (text.startsWith('Stream mapping:')) input = false;
+    if (input && !codec) codec = text.match(/Stream #0:\d+.*Video: (\w+)/)?.[1];
+    if (input && /Stream #0:\d+.*Audio:/.test(text)) hasAudio = true;
+    if (text.includes('Parsed_showinfo')) {
+      const rate = text.match(/config in time_base:\s*(\d+)\/(\d+), frame_rate:\s*(\d+)\/(\d+)/);
+      if (rate) { timeBase = Number(rate[1]) / Number(rate[2]); fps = Number(rate[3]) / Number(rate[4]); }
+      const frame = text.match(/\bn:\s*\d+\s+pts:\s*(-?\d+)\s+pts_time:.*?fmt:(\S+).*?\bs:(\d+)x(\d+)/);
+      if (frame) {
+        frames++;
+        const t = Number(frame[1]) * timeBase;
+        const duration = Number(text.match(/\bduration:\s*(\d+)/)?.[1]) * timeBase;
+        minTime = Math.min(minTime, t); maxTime = Math.max(maxTime, t + (duration > 0 ? duration : 1 / fps));
+        pixelFormat = frame[2]; width = Number(frame[3]); height = Number(frame[4]);
+      }
+    }
+    if (text.includes('Parsed_ashowinfo')) {
+      const audio = text.match(/pts_time:([\d.e+-]+).*?rate:(\d+).*?nb_samples:(\d+)/);
+      if (audio) { audioStart = Math.min(audioStart, Number(audio[1])); audioEnd = Math.max(audioEnd, Number(audio[1]) + Number(audio[3]) / Number(audio[2])); }
+    }
+  };
+
+  await probePass(ffmpeg, [...(options.alpha && options.format === 'webm' ? ['-c:v', 'libvpx-vp9'] : []), '-i', file,
+    '-map', '0:v:0', '-an', '-vf', 'showinfo=checksum=0', '-fps_mode', 'passthrough', '-f', 'null', '-'], events, spawnProcess, line);
+  if (packetCount !== frames) throw new MultiplaneError('output_invalid', 'Video packet count and decoded frame count disagree.', {
+    details: { reason: 'video_count_mismatch', packetCount, decodedFrames: frames },
+  });
+  if (!frames || !width || !height || !Number.isFinite(fps) || fps <= 0 || !Number.isFinite(maxTime - minTime) || maxTime <= minTime || !codec || !pixelFormat) throw new Error('FFmpeg probe output could not be parsed.');
+  if (hasAudio) {
+    await probePass(ffmpeg, ['-i', file, '-map', '0:a:0', '-vn', '-af', 'ashowinfo', '-f', 'null', '-'], events, spawnProcess, line);
+    if (!Number.isFinite(audioEnd - audioStart) || audioEnd <= audioStart) throw new Error('FFmpeg audio duration could not be parsed.');
+  }
+  return { frames, durationSeconds: maxTime - minTime, width, height, fps, codec, pixelFormat,
+    // TODO(design): Document the optional audioDurationSeconds field.
+    ...(Number.isFinite(audioEnd) ? { audioDurationSeconds: audioEnd - audioStart } : {}) };
+}
+
+export async function checkVideo(ffmpeg, file, expected, events, probe = probeVideo) {
+  let actual;
+  try { actual = await probe(ffmpeg, file, events, undefined, expected); }
+  catch (error) {
+    events.check();
+    if (error.code === 'output_invalid') throw error;
+    if (expected.alpha) throw new MultiplaneError('output_invalid', 'Transparent output could not be verified.', { cause: error });
+    events.warning({ code: 'output_unverified', message: 'Output could not be verified.', details: { reason: error.message } });
+    return { verified: false, frames: null, durationSeconds: null, width: null, height: null, fps: null, codec: null, pixelFormat: null };
+  }
+  events.check();
+  const durationPrecision = 8 * Number.EPSILON * Math.max(1, expected.durationSeconds, actual.durationSeconds);
+  const mismatch = ['frames', 'width', 'height'].some(key => actual[key] !== expected[key])
+    || Math.abs(actual.fps - expected.fps) / expected.fps > FRAME_RATE_RELATIVE_TOLERANCE
+    || Math.abs(actual.durationSeconds - expected.durationSeconds) - 1 / expected.fps > durationPrecision;
+  if (expected.alpha && !/^(yuva|gbrap|rgba|bgra|argb|abgr)/.test(actual.pixelFormat)) throw new MultiplaneError('output_invalid', 'Decoded output has no alpha channel.', { details: { actual } });
+  if (mismatch) throw new MultiplaneError('output_invalid', undefined, { details: { expected, actual } });
+  return { verified: true, ...actual };
+}
+
+export async function checkStill(file, expected) {
+  let actual = { width: null, height: null };
+  try {
+    const decoded = await decodeNativePNG(await readFile(file));
+    actual = { width: decoded.width, height: decoded.height };
+    if (actual.width === expected.width && actual.height === expected.height) return;
+  } catch {}
+  await rm(file, { force: true });
+  throw new MultiplaneError('output_invalid', 'Still image could not be decoded or has incorrect dimensions.', { details: { expected, actual } });
+}