video-fps-probe 0.0.0-stage → 0.2.0

package/dist/check/index.js

@@ -0,0 +1,271 @@
+const UNEVEN_SPREAD = 1.075;
+const DECIMATE_FROM = [3n, 2n];
+const SPAN_SLACK_MS = 3n;
+const MAX_EXPONENT = 400;
+const NOMINAL_SLACK_PER_S = 10000000n;
+const NTSC = [24n, 30n, 48n, 60n, 120n];
+const STANDARD = [...[24n, 25n, 30n, 48n, 50n, 60n, 100n, 120n].map((m) => [m, 1n]), ...NTSC.map((m) => [m * 1000n, 1001n])];
+const RELATION = { min: 'below the minimum', max: 'above the maximum', exact: 'not', oneOf: 'not one of' };
+const BOUNDS = Object.keys(RELATION);
+const GROUPS = ['fps', 'duration', 'frameSize', 'aspectRatio', 'pixels', 'fileSize'];
+const POLICIES = ['allow', 'warn', 'reject'];
+const SOURCES = ['avg', 'ffprobe', 'nominal', 'dominant'];
+const AUDIO_ENGINES = ['own', 'mp4box', 'mediabunny'];
+const RANGE = ['min', 'max'];
+const FILE_RULES = ['fileSize', 'containers', 'audio'];
+const GROUP_KEYS = {
+    fps: [...RANGE, 'exact', 'oneOf', 'source'],
+    duration: RANGE,
+    frameSize: ['Width', 'Height', 'ShortSide', 'LongSide'].flatMap((side) => RANGE.map((b) => b + side)),
+    aspectRatio: [...RANGE, 'oneOf'],
+    pixels: RANGE,
+    fileSize: RANGE,
+};
+const RULE_KEYS = [...GROUPS, 'containers', 'codecs', 'audio', 'vfr', 'uneven', 'severity'];
+const invalid = (rule, v, what) => {
+    throw new TypeError(`${rule}: ${typeof v === 'number' ? v : JSON.stringify(v)} is not ${what}`);
+};
+function decimal(s) {
+    const m = /^(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/i.exec(s.trim());
+    if (!m || !Number.isFinite(Number(m[0])))
+        return null;
+    const e = Number(m[3] ?? 0) - (m[2]?.length ?? 0);
+    if (Math.abs(e) > MAX_EXPONENT)
+        return null;
+    const n = BigInt(m[1] + (m[2] ?? ''));
+    return e >= 0 ? [n * 10n ** BigInt(e), 1n] : [n, 10n ** BigInt(-e)];
+}
+function ratio(v, rule, amount = false) {
+    const parts = typeof v === 'number' || typeof v === 'string' ? String(v).split(/[/:]/) : [];
+    const [a, b] = parts.map(decimal);
+    const q = a && parts.length === 1 ? a : a && b && parts.length === 2 && !amount ? [a[0] * b[1], a[1] * b[0]] : null;
+    const ratios = parts.length > 1 ? "; 'num/den' and 'num:den' ratios are for fps and aspectRatio" : '';
+    return q && q[1] !== 0n ? q : invalid(rule, v, amount ? `a non-negative number${ratios}` : "a non-negative number or 'num/den'");
+}
+const cmp = (a, b) => a[0] * b[1] - b[0] * a[1];
+const ntsc = (v, q) => (/[/:]/.test(String(v)) ? [] : NTSC.filter((m) => q[0] * 1000n === q[1] * m * 999n).map((m) => [m * 1000n, 1001n]));
+const readings = (v, rule) => {
+    const q = ratio(v, rule);
+    return [q, ...ntsc(v, q)];
+};
+function close(n, a, b, slack, perSecond) {
+    const gap = n * (a[1] * b[0] - b[1] * a[0]);
+    return (gap < 0n ? -gap : gap) * perSecond <= slack * a[0] * b[0];
+}
+const whole = (x) => Number.isSafeInteger(x) && x > 0;
+const record = (x) => !!x && typeof x === 'object' && !Array.isArray(x);
+function primaryTrack(result) {
+    const list = result.videoTracks;
+    const id = result.primaryTrackId;
+    if (!Array.isArray(list))
+        return 'the result has no videoTracks list';
+    if (list.length === 0)
+        return 'no video track';
+    const track = list.find((x) => record(x) && typeof id === 'number' && x.trackId === id);
+    return track || `no primary track: primaryTrackId ${id === undefined ? 'is missing' : `${JSON.stringify(id)} matches no video track`}`;
+}
+const errorKind = (e) => (typeof e === 'string' ? 'blank' : Array.isArray(e) ? 'a list' : `of type ${typeof e}`);
+const failedWith = (e) => `the analysis failed${typeof e === 'string' && e.trim() ? `: ${e}` : `, and its error is ${errorKind(e)}`}`;
+const fromRational = (r) => (r && whole(r.num) && whole(r.den) ? [BigInt(r.num), BigInt(r.den)] : null);
+const gcd = (a, b) => (b === 0n ? a : gcd(b, a % b));
+const value = (q) => Number(q[0]) / Number(q[1]);
+const round = (x) => +x.toFixed(3);
+function digits(q, against) {
+    let d = 3;
+    while (d < 12 && against.some((b) => value(b).toFixed(d) === value(q).toFixed(d)))
+        d++;
+    return +value(q).toFixed(d);
+}
+function fraction(q) {
+    const g = gcd(q[0], q[1]) || 1n;
+    return `${q[0] / g}/${q[1] / g}`;
+}
+const fpsText = (q, against = []) => (q[0] % q[1] === 0n ? `${q[0] / q[1]}` : `${digits(q, against)} (${fraction(q)})`);
+function steady(t) {
+    const avg = fromRational(t.avgFps);
+    const nominal = fromRational(t.nominalFps);
+    const frames = t.presentedFrames ?? t.frames;
+    if (!avg || !nominal || !t.timestampsQuantized || t.isVfr !== false || !whole(frames))
+        return null;
+    const n = BigInt(frames);
+    return close(n, avg, nominal, SPAN_SLACK_MS, 1000n) ? [nominal, [n * nominal[1], nominal[0]]] : null;
+}
+function resolution(t, cfr) {
+    const avg = fromRational(t.avgFps);
+    const frames = t.presentedFrames ?? t.frames;
+    if (!avg || !t.timestampsQuantized || t.isVfr !== false || !whole(frames))
+        return undefined;
+    return cfr ? (x) => close(1n, cfr[0], x, 1n, NOMINAL_SLACK_PER_S) : (x) => close(BigInt(frames), avg, x, SPAN_SLACK_MS, 1000n);
+}
+function judgedFps(t, source, cfr) {
+    const m = /^(\d+)\/(\d+)$/.exec(t.avgFpsFfprobe ?? '');
+    if (source === 'ffprobe')
+        return m && fromRational({ num: +m[1], den: +m[2] });
+    if (source === 'nominal')
+        return fromRational(t.nominalFps);
+    if (source === 'dominant')
+        return fromRational(t.dominantFps?.rate ?? (t.isVfr === false ? t.nominalFps : null));
+    return cfr?.[0] ?? fromRational(t.avgFps);
+}
+function unevenOf(t) {
+    const p = t.rateProfile;
+    if (p != null)
+        return record(p) ? p.uneven : null;
+    return t.isVfr === false || (t.minFps && t.maxFps && t.maxFps.value <= t.minFps.value * UNEVEN_SPREAD) ? false : null;
+}
+const abs = (x) => (x < 0n ? -x : x);
+function fit(target, rule = {}) {
+    const list = (v) => (v == null ? [] : [v].flat().flatMap((x) => readings(x, 'fps')));
+    const [lo] = list(rule.min);
+    const hi = list(rule.max).reduce((a, q) => (a && cmp(a, q) > 0 ? a : q), undefined);
+    const inside = (q) => (!lo || cmp(q, lo) >= 0) && (!hi || cmp(q, hi) <= 0);
+    const nearer = (a, b) => abs(cmp(a, target)) * b[1] - abs(cmp(b, target)) * a[1] || cmp(a, b);
+    const nearest = (qs) => qs.filter(inside).reduce((b, q) => (b && nearer(b, q) <= 0n ? b : q), null);
+    const divided = (keep) => {
+        for (let k = 2n; k <= 8n; k++) {
+            const q = [target[0], target[1] * k];
+            if (keep(q))
+                return [q, Number(k)];
+        }
+    };
+    const oneOf = rule.oneOf == null ? null : list(rule.oneOf);
+    const named = rule.exact == null ? oneOf : list(rule.exact).filter((q) => !oneOf || oneOf.some((o) => cmp(o, q) === 0n));
+    if (lo && hi && cmp(lo, hi) > 0)
+        return null;
+    if (!named && inside(target))
+        return [target, 0];
+    const listed = (named ?? STANDARD).filter(inside);
+    const range = !named && listed.length === 0;
+    const closest = range ? (lo && cmp(target, lo) < 0 ? lo : hi) : nearest(listed);
+    if (!closest)
+        return null;
+    const allowed = range ? inside : (q) => listed.some((s) => cmp(s, q) === 0n);
+    const decimates = cmp(target, [DECIMATE_FROM[0] * closest[0], DECIMATE_FROM[1] * closest[1]]) >= 0;
+    return (decimates && divided(allowed)) || [closest, 0];
+}
+export function check(result, rules) {
+    const known = (path, v, keys) => {
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            invalid(path, v, 'an object');
+        const prefix = path === 'rules' ? '' : `${path}.`;
+        for (const k of Object.keys(v))
+            if (!keys.includes(k))
+                throw new TypeError(`${prefix}${k}: not a rule; expected one of ${keys.join(', ')}`);
+    };
+    known('rules', rules, RULE_KEYS);
+    for (const g of GROUPS)
+        if (rules[g] != null)
+            known(g, rules[g], GROUP_KEYS[g]);
+    const choices = [
+        ['fps.source', rules.fps?.source, SOURCES],
+        ['audio', rules.audio, ['required', 'forbidden']],
+        ['vfr', rules.vfr, POLICIES],
+        ['uneven', rules.uneven, POLICIES],
+        ['severity', rules.severity, ['fail', 'warn']],
+    ];
+    for (const [rule, v, list] of choices)
+        if (v != null && !list.includes(v))
+            invalid(rule, v, `one of ${list.join(', ')}`);
+    const violations = [];
+    const severity = rules.severity === 'warn' ? 'warn' : 'fail';
+    const failure = result == null ? 'the analysis failed: no result' : result.error ? failedWith(result.error) : null;
+    const found = failure ?? primaryTrack(result);
+    const t = typeof found === 'string' ? null : found;
+    const add = (rule, s, expected, actual, message) => violations.push({ rule, severity: s, expected, actual, message: `${rule}: ${message}` });
+    const unknown = (rule, missing) => violations.some((v) => v.rule === rule) ||
+        add(rule, 'unknown', null, null, `unknown, ${t || FILE_RULES.includes(rule) ? `no ${missing}${failure ? `; ${failure}` : ''}` : found}`);
+    const limits = (group, rule, actual, shown, text, unit, missing, side = '', near) => {
+        const bounds = BOUNDS.filter((b) => rule?.[b] != null).map((b) => {
+            const path = `${group}.${b}${side}`;
+            const values = (b === 'oneOf' ? [rule[b]].flat() : [rule[b]]).map((v) => (group === 'fps' ? readings(v, path) : [ratio(v, path, group !== 'aspectRatio')]));
+            return [b, rule[b], values];
+        });
+        if (bounds.length === 0)
+            return;
+        if (!actual)
+            return void unknown(group, missing);
+        for (const [b, expected, values] of bounds) {
+            const meets = (q) => near?.(q) || (b === 'min' ? cmp(actual, q) >= 0n : b === 'max' ? cmp(actual, q) <= 0n : cmp(actual, q) === 0n);
+            const listed = [expected].flat();
+            const named = listed.length ? `${listed.join(', ')}${unit}` : 'an empty list';
+            const actualText = typeof text === 'string' ? text : text(values.flat());
+            if (!values.flat().some(meets))
+                add(`${group}.${b}${side}`, severity, expected, shown, `${actualText}${unit} is ${RELATION[b]} ${named}`);
+        }
+    };
+    const quantity = (x) => (typeof x === 'number' ? decimal(String(x)) : null);
+    const allow = (rule, list, actual, missing) => {
+        if (list == null)
+            return;
+        if (!Array.isArray(list) || list.some((x) => typeof x !== 'string'))
+            invalid(rule, list, 'a list of strings');
+        if (typeof actual !== 'string' || !actual || actual === 'unknown')
+            unknown(rule, missing);
+        else if (!list.some((x) => x.toLowerCase() === actual.toLowerCase()))
+            add(rule, severity, list, actual, `${actual} is not one of ${list.length ? list.join(', ') : 'an empty list'}`);
+    };
+    const policy = (rule, state, missing, message) => {
+        const p = rules[rule];
+        if (!p || p === 'allow')
+            return false;
+        if (typeof state !== 'boolean')
+            unknown(rule, missing);
+        else if (state)
+            add(rule, p === 'warn' ? 'warn' : severity, p, true, message);
+        return state === true;
+    };
+    const cfr = t && steady(t);
+    const fps = t && judgedFps(t, rules.fps?.source, cfr);
+    const near = t && (rules.fps?.source ?? 'avg') === 'avg' ? resolution(t, cfr) : undefined;
+    limits('fps', rules.fps, fps, fps ? fraction(fps) : '', (against) => fpsText(fps, against), ' fps', `${rules.fps?.source ?? 'avg'} frame rate`, '', near);
+    const exact = cfr?.[1] ?? quantity(t && (t.durationSec ?? result.formatDurationSec));
+    const span = exact && [(exact[0] * 2000000n + exact[1]) / (2n * exact[1]), 1000000n];
+    const seconds = span ? value(span) : 0;
+    limits('duration', rules.duration, span, seconds, (against) => `${digits(span, against)}`, ' s', 'duration');
+    const size = t ? (Math.abs(t.rotation) % 180 === 90 ? [t.height, t.width] : [t.width, t.height]) : [0, 0];
+    const sized = size.every(whole);
+    const [w, h] = sized ? size : [0, 0];
+    const sides = { Width: w, Height: h, ShortSide: Math.min(w, h), LongSide: Math.max(w, h) };
+    const d = rules.frameSize;
+    for (const [side, x] of Object.entries(sides)) {
+        limits('frameSize', { min: d?.[`min${side}`], max: d?.[`max${side}`] }, sized ? [BigInt(x), 1n] : null, x, `${x}`, ' px', 'frame size', side);
+    }
+    const area = [BigInt(w), BigInt(h)];
+    limits('aspectRatio', rules.aspectRatio, sized ? area : null, fraction(area), `${w}x${h} (${round(w / h)})`, '', 'frame size');
+    limits('pixels', rules.pixels, sized ? [BigInt(w) * BigInt(h), 1n] : null, w * h, `${w * h}`, ' px', 'frame size');
+    limits('fileSize', rules.fileSize, quantity(result?.size), result?.size ?? '', `${result?.size}`, ' bytes', 'file size');
+    allow('containers', rules.containers, result?.container, 'container');
+    allow('codecs', rules.codecs, t?.codecName, 'codec name');
+    if (rules.audio) {
+        const engine = result?.engine;
+        const counts = AUDIO_ENGINES.includes(engine);
+        const n = result?.audioTrackCount;
+        const audio = !failure && counts && Number.isSafeInteger(n) && n >= 0 ? n > 0 : null;
+        const required = rules.audio === 'required';
+        if (audio === null)
+            unknown('audio', `audio track count${!counts && typeof engine === 'string' ? ` (the ${engine} engine reports none)` : ''}`);
+        else if (audio !== required)
+            add('audio', severity, rules.audio, audio, `${rules.audio}, the file has ${required ? 'no' : 'an'} audio track`);
+    }
+    const vfr = policy('vfr', t?.isVfr, 'VFR flag', 'the frame rate is variable');
+    const profile = t?.rateProfile;
+    const summary = record(profile) && typeof profile.summary === 'string' ? `: ${profile.summary}` : '';
+    const uneven = policy('uneven', t && unevenOf(t), `${profile == null ? '' : 'uneven flag in the '}rate profile`, `the frame rate is uneven${summary}`);
+    const report = { verdict: 'pass', violations };
+    const fpsOff = violations.some((v) => v.rule.startsWith('fps.'));
+    if (t && (fpsOff || vfr || uneven)) {
+        const constant = fpsOff ? fps : (fromRational(t.dominantFps?.rate) ?? fromRational(t.nominalFps));
+        const avg = Math.round(t.avgFps?.value ?? 0);
+        const fitted = fit(constant ?? [whole(avg) ? BigInt(avg) : 0n, 1n], rules.fps);
+        const why = fpsOff ? `${fpsText(fps, fitted ? [fitted[0]] : [])} fps is not allowed` : `the frame rate is ${vfr ? 'variable' : 'uneven'}`;
+        if (!fitted)
+            report.suggestedFps = { value: null, reason: `${why}, and no frame rate meets every bound of the fps rule` };
+        else if (fitted[0][0] > 0n) {
+            const [q, k] = fitted;
+            const how = k > 1 ? `, which keeps 1 of every ${k} frames` : '';
+            report.suggestedFps = { value: value(q), reason: `${why}: ${fpsOff ? 'convert to' : 're-encode at a constant'} ${fpsText(q)} fps${how}` };
+        }
+    }
+    report.verdict = ['fail', 'unknown', 'warn'].find((s) => violations.some((v) => v.severity === s)) ?? 'pass';
+    return report;
+}

package/dist/client/compare.js

@@ -0,0 +1,57 @@
+import { compareResults } from "../api/agreement.js";
+import { ProbeError } from "../api/errors.js";
+import { isAbortError } from "../api/guards.js";
+import { failureOf } from "./fallback.js";
+import { nameOf } from "./probe.js";
+export async function compare(ctx, file, o = {}) {
+    const name = nameOf(file);
+    const ids = [...new Set(o.engines ?? ctx.engines.filter((id) => id !== 'rvfc'))];
+    const missing = ids.find((id) => !ctx.routes.has(id));
+    if (missing)
+        throw new ProbeError('engine-not-registered', `engine ${missing} is not registered`, { engine: missing });
+    const wire = { ...ctx.defaults };
+    const { signal, timeoutMs, onProgress } = o;
+    const outcomeOf = async (id) => {
+        const t0 = performance.now();
+        try {
+            const reply = await ctx.run(id, file, name, wire, { signal, timeoutMs, onProgress: onProgress && ((p) => onProgress({ ...p, engine: id })) });
+            if (reply.type === 'skipped')
+                return { status: 'skipped', reason: reply.reason };
+            const ms = performance.now() - t0;
+            const result = reply.result;
+            const error = failureOf(result);
+            return error === null ? { status: 'ok', result, ms } : { status: 'failed', result, error, ms };
+        }
+        catch (e) {
+            if (isAbortError(e))
+                throw e;
+            const error = e instanceof ProbeError ? e : Object.assign(new ProbeError('worker-failed', String(e), { engine: id, cause: e }), { reason: 'crash' });
+            if (error.code === 'unsupported-environment')
+                return { status: 'skipped', reason: 'unsupported-environment' };
+            return { status: error.code === 'timeout' ? 'timeout' : 'crashed', error };
+        }
+    };
+    const groups = new Map();
+    for (const id of ids) {
+        const route = ctx.routes.get(id);
+        const kind = route && 'kind' in route ? route.kind : id;
+        groups.set(kind, [...(groups.get(kind) ?? []), id]);
+    }
+    const settled = new Map();
+    await Promise.all([...groups.values()].map(async (group) => {
+        for (const id of group)
+            settled.set(id, await outcomeOf(id));
+    }));
+    const outcomes = {};
+    const results = {};
+    for (const id of ids) {
+        const outcome = settled.get(id);
+        if (!outcome)
+            continue;
+        outcomes[id] = outcome;
+        if ('result' in outcome)
+            results[id] = outcome.result;
+    }
+    const agreement = compareResults(results, o.reference);
+    return { name, size: file.size, reference: agreement.reference, outcomes, agreement };
+}

package/dist/client/fallback.js

@@ -0,0 +1,43 @@
+import { ProbeError } from "../api/errors.js";
+import { isAbortError } from "../api/guards.js";
+import { emptyAnalysis, primaryTrack } from "../core/result.js";
+export const failureOf = (r) => {
+    const t = primaryTrack(r);
+    return r.error ?? (!t ? 'no video track' : t.avgFps ? null : 'no frame rate');
+};
+const skippedResult = (id, file, name, family) => ({
+    name,
+    size: file.size,
+    ...emptyAnalysis(family === 'isobmff' ? 'mp4' : (family ?? 'unknown'), family ? `unsupported by ${id}` : 'not a recognised container'),
+    io: { reads: 0, bytesRead: 0, ms: 0 },
+    engine: id,
+});
+const withAttempts = (result, failures) => failures.length > 0 ? { ...result, attempts: failures.map(({ engine, error }) => ({ engine, error })) } : result;
+export async function runChain(run, chain, file, name, wire, call, first) {
+    const failures = [];
+    let last = null;
+    for (const [i, id] of chain.entries()) {
+        let result;
+        try {
+            const reply = i === 0 && first ? first : await run(id, file, name, wire, call);
+            result = reply.type === 'result' ? reply.result : skippedResult(id, file, name, reply.family ?? null);
+        }
+        catch (e) {
+            if (isAbortError(e))
+                throw e;
+            last = e instanceof ProbeError ? e : Object.assign(new ProbeError('worker-failed', String(e), { engine: id, cause: e }), { reason: 'crash' });
+            failures.push({ engine: id, error: last.message });
+            continue;
+        }
+        const error = failureOf(result);
+        if (error === null || chain.length === 1)
+            return withAttempts(result, failures);
+        failures.push({ engine: id, error, result });
+    }
+    for (let i = failures.length - 1; i >= 0; i--) {
+        const { result } = failures[i];
+        if (result)
+            return withAttempts(result, failures.slice(0, i).concat(failures.slice(i + 1)));
+    }
+    throw last;
+}

package/dist/client/index.d.ts

@@ -0,0 +1,11 @@
+export { compareResults, type Agreement, type ComparedField, type ComparedFieldName, type ComparedValue } from '../api/agreement.js';
+export { ProbeError, type ProbeErrorCode } from '../api/errors.js';
+export { isAbortError, isTimeoutError } from '../api/guards.js';
+export { summarize, type VideoFpsSummary } from '../api/summary.js';
+export type { BlobLike, BlobSlice } from '../core/reader.js';
+export type * from '../core/types.js';
+export type { MediabunnyNative, MediabunnyTrackNative, Mp4boxNative, Mp4boxTrackNative, RvfcConfidence, RvfcDetails, RvfcPass } from '../engines/types.js';
+export type { ContainerFamily, EngineDescriptor, EngineModule, WorkerEngineId } from '../plugins/types.js';
+export type { WireOptions } from '../worker/protocol.js';
+export { createProbeClient } from './probe.js';
+export type * from './types.js';

package/dist/client/index.js

@@ -0,0 +1,5 @@
+export { compareResults } from "../api/agreement.js";
+export { ProbeError } from "../api/errors.js";
+export { isAbortError, isTimeoutError } from "../api/guards.js";
+export { summarize } from "../api/summary.js";
+export { createProbeClient } from "./probe.js";

package/dist/client/inline.d.ts

@@ -0,0 +1,19 @@
+import type { AnalyzeProgress, EngineId, FileResult } from '../core/types.js';
+import type { ContainerFamily, EngineModule } from '../plugins/types.js';
+import type { SkipReason, WireOptions } from '../worker/protocol.js';
+export interface InlineRun {
+    engine: EngineId;
+    signals: readonly (AbortSignal | null | undefined)[];
+    timeoutMs?: number;
+    onProgress?: (progress: AnalyzeProgress) => void;
+    host?: HTMLElement;
+}
+export type InlineReply = {
+    type: 'result';
+    result: FileResult;
+} | {
+    type: 'skipped';
+    reason: SkipReason;
+    family: ContainerFamily | null;
+};
+export declare function runInline(load: () => Promise<EngineModule>, file: Blob, name: string, options: WireOptions, run: InlineRun): Promise<InlineReply>;

package/dist/client/inline.js

@@ -0,0 +1,43 @@
+import { ProbeError } from "../api/errors.js";
+import { containerFamily } from "../core/sniff.js";
+export function runInline(load, file, name, options, run) {
+    const { engine, signals, onProgress, host } = run;
+    const timeoutMs = run.timeoutMs ?? 0;
+    const controller = new AbortController();
+    return new Promise((resolve, reject) => {
+        let done = false;
+        let timer;
+        const finish = (settle) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            for (const s of signals)
+                s?.removeEventListener('abort', onAbort);
+            settle();
+        };
+        const fail = (error) => {
+            controller.abort();
+            finish(() => reject(error));
+        };
+        const onAbort = () => fail(new ProbeError('aborted', 'aborted', { engine, cause: signals.find((s) => s?.aborted)?.reason }));
+        if (signals.some((s) => s?.aborted))
+            return onAbort();
+        for (const s of signals)
+            s?.addEventListener('abort', onAbort);
+        if (timeoutMs > 0 && timeoutMs <= 2 ** 31 - 1)
+            timer = setTimeout(() => fail(new ProbeError('timeout', `timed out after ${timeoutMs} ms`, { engine })), timeoutMs);
+        let loading = true;
+        (async () => {
+            const module = await load();
+            loading = false;
+            if (module.containers !== 'any') {
+                const family = await containerFamily(file);
+                if (!family || !module.containers.includes(family))
+                    return { type: 'skipped', reason: 'unsupported-container', family };
+            }
+            const opts = { ...options, signal: controller.signal, onProgress, host };
+            return { type: 'result', result: await module.run(file, name, opts) };
+        })().then((reply) => finish(() => resolve(reply)), (e) => (e instanceof ProbeError ? finish(() => reject(e)) : fail(Object.assign(new ProbeError('worker-failed', e instanceof Error ? e.message || e.name : String(e), { engine, cause: e }), { reason: loading ? 'load' : 'crash' }))));
+    });
+}

package/dist/client/lazy.d.ts

@@ -0,0 +1,6 @@
+import type { EngineId } from '../core/types.js';
+import type { EngineDescriptor, WorkerEngineId } from '../plugins/types.js';
+import type { ClientOptions, IdOf, LazyProbe, Probe } from './types.js';
+export type { ClientOptions, LazyProbe, Probe };
+export declare function lazyProbeFrom<Id extends EngineId>(factory: () => Promise<Probe<Id>>): LazyProbe<Id>;
+export declare function lazyProbeClient<const E extends readonly EngineDescriptor[] = [], const W extends WorkerEngineId = never>(options: ClientOptions<E, W>): LazyProbe<W | IdOf<E[number]> | 'own'>;

package/dist/client/lazy.js

@@ -0,0 +1,7 @@
+import { knownEngines, lazyStub } from "./stub.js";
+export function lazyProbeFrom(factory) {
+    return lazyStub(factory, []);
+}
+export function lazyProbeClient(options) {
+    return lazyStub(() => import("./probe.js").then((m) => m.createProbeClient(options)), knownEngines(options.worker, options.engines));
+}

package/dist/client/pool.d.ts

@@ -0,0 +1,29 @@
+import { ProbeError } from '../api/errors.js';
+import type { AnalyzeProgress, EngineId } from '../core/types.js';
+import { type JobRequest, type WorkerResponse } from '../worker/protocol.js';
+export declare const KILL_AFTER_MS = 1500;
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 30000;
+export declare const LOAD_FAILED = "worker script failed to load or parse; the app may have been redeployed";
+export declare const workerFailed: (message: string, reason: NonNullable<ProbeError["reason"]>, engine?: EngineId | null, cause?: unknown) => ProbeError;
+export interface PoolOptions {
+    create: () => Worker;
+    size?: number;
+    idleTimeoutMs?: number;
+}
+export interface RunOptions {
+    signal?: AbortSignal | null;
+    timeoutMs?: number;
+    onProgress?: (progress: AnalyzeProgress) => void;
+    engine?: EngineId | null;
+}
+export type PoolReply = Extract<WorkerResponse, {
+    type: 'result' | 'skipped' | 'warmed';
+}>;
+export declare class WorkerPool {
+    #private;
+    constructor(options: PoolOptions);
+    get workers(): number;
+    run(request: JobRequest, options?: RunOptions): Promise<PoolReply>;
+    dispose(): void;
+    destroy(): void;
+}