@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/serve/webgl.js

@@ -0,0 +1,415 @@
+import { createServer } from 'node:http';
+import { createReadStream, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { open, readFile } from 'node:fs/promises';
+import { extname, join, normalize, relative, resolve, sep } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+import { brotliCompress, brotliDecompressSync, constants, createBrotliCompress, createGzip, gunzipSync, gzip, gzipSync } from 'node:zlib';
+export const DEFAULT_PORT = 5794;
+export const BR_QUALITY = 5;
+export const GZIP_LEVEL = 6;
+export const STREAM_ABOVE = 1024 * 1024;
+export const DEFAULT_CACHE_BYTES = 512 * 1024 * 1024;
+const WORTH = 0.95;
+const SAMPLE = 256 * 1024;
+export const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.wasm': 'application/wasm',
+    '.data': 'application/octet-stream',
+    '.mem': 'application/octet-stream',
+    '.unityweb': 'application/octet-stream',
+    '.symbols': 'application/octet-stream',
+    '.bundle': 'application/octet-stream',
+    '.json': 'application/json',
+    '.css': 'text/css',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.webp': 'image/webp',
+    '.txt': 'text/plain; charset=utf-8',
+    '.xml': 'application/xml',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+    '.ogg': 'audio/ogg',
+    '.wav': 'audio/wav',
+    '.ttf': 'font/ttf',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+export function storedAs(path) {
+    if (path.endsWith('.br'))
+        return { stored: 'br', ext: extname(path.slice(0, -3)).toLowerCase() };
+    if (path.endsWith('.gz'))
+        return { stored: 'gzip', ext: extname(path.slice(0, -3)).toLowerCase() };
+    return { stored: null, ext: extname(path).toLowerCase() };
+}
+export function accepted(header) {
+    const out = new Set();
+    const refused = new Set();
+    let star = false;
+    for (const part of (header ?? '').split(',')) {
+        const [name, ...params] = part.trim().toLowerCase().split(';');
+        if (!name)
+            continue;
+        const q = params.map((x) => /^\s*q=([\d.]+)/.exec(x)?.[1]).find(Boolean);
+        if (q !== undefined && Number(q) === 0)
+            refused.add(name);
+        else if (name === '*')
+            star = true;
+        else
+            out.add(name);
+    }
+    if (star)
+        for (const c of ['br', 'gzip'])
+            if (!refused.has(c))
+                out.add(c);
+    for (const r of refused)
+        out.delete(r);
+    return out;
+}
+export function pickEncoding(stored, acceptEncoding, secure) {
+    if (!stored)
+        return 'identity';
+    const ok = accepted(acceptEncoding);
+    if (stored === 'br' && secure && ok.has('br'))
+        return 'br';
+    return ok.has('gzip') ? 'gzip' : 'identity';
+}
+const NEVER = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.ico', '.ktx2', '.basis', '.dds', '.mp3', '.ogg', '.m4a', '.aac', '.wav', '.flac', '.opus', '.mp4', '.webm', '.mov', '.woff', '.woff2', '.zip', '.gz', '.br', '.zst', '.xz', '.7z', '.unityweb']);
+const UNITY_PLAIN = new Set(['.bundle', '.json', '.wasm', '.data']);
+const TEXT = new Set(['.js', '.mjs', '.css', '.html', '.svg', '.txt', '.xml', '.map']);
+const ADDRESSABLES = /(^|\/)StreamingAssets\/aa\//;
+export function compressible(rel, hasTwin) {
+    const ext = extname(rel).toLowerCase();
+    if (NEVER.has(ext))
+        return false;
+    if (TEXT.has(ext))
+        return true;
+    if (hasTwin)
+        return false;
+    return UNITY_PLAIN.has(ext) || ADDRESSABLES.test(rel);
+}
+export function looksCompressed(head) {
+    const starts = (...b) => b.every((x, i) => head[i] === x);
+    return starts(0x1f, 0x8b) || starts(0x50, 0x4b, 0x03, 0x04) || starts(0x28, 0xb5, 0x2f, 0xfd) || starts(0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00) || starts(0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c) || starts(0x42, 0x5a, 0x68);
+}
+export function isLoopbackHost(hostHeader) {
+    const host = (hostHeader ?? '').trim().toLowerCase();
+    const name = host.startsWith('[') ? host.slice(1, host.indexOf(']')) : host.replace(/:\d+$/, '');
+    return name === 'localhost' || name.endsWith('.localhost') || /^127\.\d+\.\d+\.\d+$/.test(name) || name === '::1';
+}
+const secureRequest = (req) => isLoopbackHost(req.headers.host) || String(req.headers['x-forwarded-proto'] ?? '').split(',')[0].trim() === 'https' || req.socket.encrypted === true;
+export function isWebglBuild(dir) {
+    if (!existsSync(join(dir, 'index.html')))
+        return false;
+    try {
+        return readdirSync(join(dir, 'Build')).some((f) => f.endsWith('.loader.js'));
+    }
+    catch {
+        return false;
+    }
+}
+export function buildDir(dir) {
+    const d = resolve(dir);
+    if (existsSync(join(d, 'index.html')))
+        return d;
+    for (const sub of [['Builds', 'WebGL'], ['Build', 'WebGL'], ['Builds', 'Web']])
+        if (existsSync(join(d, ...sub, 'index.html')))
+            return join(d, ...sub);
+    return null;
+}
+export const brotliBuild = (dir) => {
+    try {
+        return readdirSync(join(dir, 'Build')).some((f) => f.endsWith('.br'));
+    }
+    catch {
+        return false;
+    }
+};
+export function byteRange(header, size) {
+    const m = /^bytes=(\d*)-(\d*)$/.exec((header ?? '').trim());
+    if (!m || (!m[1] && !m[2]))
+        return null;
+    let start;
+    let end;
+    if (!m[1]) {
+        const n = Number(m[2]);
+        if (n === 0)
+            return 'bad';
+        start = Math.max(0, size - n);
+        end = size - 1;
+    }
+    else {
+        start = Number(m[1]);
+        end = m[2] ? Math.min(Number(m[2]), size - 1) : size - 1;
+    }
+    return start >= size || start > end ? 'bad' : [start, end];
+}
+export class ByteLru {
+    map = new Map();
+    total = 0;
+    cap;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    get(key) {
+        const v = this.map.get(key);
+        if (v) {
+            this.map.delete(key);
+            this.map.set(key, v);
+        }
+        return v;
+    }
+    set(key, v) {
+        this.delete(key);
+        if (v.bytes > this.cap)
+            return;
+        this.map.set(key, v);
+        this.total += v.bytes;
+        for (const [k, old] of this.map) {
+            if (this.total <= this.cap)
+                break;
+            this.map.delete(k);
+            this.total -= old.bytes;
+        }
+    }
+    delete(key) {
+        const v = this.map.get(key);
+        if (v) {
+            this.map.delete(key);
+            this.total -= v.bytes;
+        }
+    }
+    get size() {
+        return this.total;
+    }
+}
+class Tap extends Transform {
+    chunks = [];
+    length = 0;
+    overflowed = false;
+    keep;
+    onBytes;
+    onEnd;
+    constructor(keep, onBytes, onEnd) {
+        super();
+        this.keep = keep;
+        this.onBytes = onBytes;
+        this.onEnd = onEnd;
+    }
+    _transform(chunk, _enc, done) {
+        this.length += chunk.length;
+        this.onBytes(chunk.length);
+        if (this.length > this.keep) {
+            this.overflowed = true;
+            this.chunks = [];
+        }
+        else
+            this.chunks.push(chunk);
+        done(null, chunk);
+    }
+    _flush(done) {
+        this.onEnd?.(this);
+        done();
+    }
+}
+const brParams = (size) => ({ params: { [constants.BROTLI_PARAM_QUALITY]: BR_QUALITY, [constants.BROTLI_PARAM_SIZE_HINT]: size } });
+const brotliAsync = promisify(brotliCompress);
+const gzipAsync = promisify(gzip);
+async function headOf(file, n) {
+    const fh = await open(file, 'r');
+    try {
+        const b = Buffer.alloc(n);
+        const { bytesRead } = await fh.read(b, 0, n, 0);
+        return b.subarray(0, bytesRead);
+    }
+    finally {
+        await fh.close();
+    }
+}
+const pack = (plain, enc) => enc === 'br' ? brotliAsync(plain, brParams(plain.length)) : gzipAsync(plain, { level: GZIP_LEVEL });
+export function webglHandler(root, options = {}) {
+    const base = resolve(root);
+    const compress = options.compress ?? true;
+    const streamAbove = options.streamAbove ?? STREAM_ABOVE;
+    const cache = new ByteLru(options.cacheBytes ?? DEFAULT_CACHE_BYTES);
+    const stats = { files: 0, wire: 0, stored: 0, compressed: 0, hits: 0, misses: 0 };
+    const lookup = (file, enc, st) => {
+        const key = `${file}\0${enc}`;
+        const hit = cache.get(key);
+        if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size)
+            return hit;
+        if (hit)
+            cache.delete(key);
+        return undefined;
+    };
+    const keep = (file, enc, st, body) => cache.set(`${file}\0${enc}`, { mtimeMs: st.mtimeMs, size: st.size, body, bytes: (body?.length ?? 0) + file.length + 64 });
+    const recoded = (file, stored, to) => {
+        const st = statSync(file);
+        const hit = lookup(file, `recode-${to}`, st);
+        if (hit?.body)
+            return hit.body;
+        const bytes = readFileSync(file);
+        const plain = stored === 'br' ? brotliDecompressSync(bytes) : gunzipSync(bytes);
+        const body = to === 'gzip' ? gzipSync(plain, { level: GZIP_LEVEL }) : plain;
+        keep(file, `recode-${to}`, st, body);
+        return body;
+    };
+    const handler = (req, res) => {
+        const head = req.method === 'HEAD';
+        const send = (status, text, extra = {}) => {
+            res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-cache', ...extra });
+            res.end(head ? undefined : text);
+        };
+        if (req.method !== 'GET' && !head)
+            return send(405, 'GET or HEAD only\n');
+        let path;
+        try {
+            path = decodeURIComponent(new URL(req.url ?? '/', 'http://x').pathname);
+        }
+        catch {
+            return send(400, 'bad path\n');
+        }
+        if (path.includes('\0'))
+            return send(400, 'bad path\n');
+        let file = normalize(join(base, path));
+        if (file !== base && !file.startsWith(base + sep))
+            return send(403, 'outside the build\n');
+        try {
+            if (statSync(file).isDirectory())
+                file = join(file, 'index.html');
+        }
+        catch {
+        }
+        if (!existsSync(file) || !statSync(file).isFile())
+            return send(404, 'not in this build\n');
+        const st = statSync(file);
+        const { stored, ext } = storedAs(file);
+        const headers = { 'Content-Type': MIME[ext] ?? 'application/octet-stream', 'Cache-Control': 'no-cache' };
+        const finish = (body, compressed = false) => {
+            headers['Content-Length'] = String(body.length);
+            res.writeHead(200, headers);
+            res.end(head ? undefined : body);
+            if (!head) {
+                stats.files++;
+                stats.wire += body.length;
+                stats.stored += st.size;
+                if (compressed)
+                    stats.compressed++;
+            }
+        };
+        if (stored) {
+            headers.Vary = 'Accept-Encoding';
+            const enc = pickEncoding(stored, req.headers['accept-encoding'], secureRequest(req));
+            let body;
+            try {
+                body = enc === stored ? readFileSync(file) : recoded(file, stored, enc === 'br' ? 'identity' : enc);
+            }
+            catch {
+                return send(500, `could not decode ${path}: is it really ${stored}?\n`);
+            }
+            if (enc !== 'identity')
+                headers['Content-Encoding'] = enc;
+            return finish(body);
+        }
+        const rel = relative(base, file).split(sep).join('/');
+        const live = compress && compressible(rel, existsSync(`${file}.br`) || existsSync(`${file}.gz`));
+        if (live)
+            headers.Vary = 'Accept-Encoding';
+        headers['Accept-Ranges'] = 'bytes';
+        const range = req.headers.range === undefined ? null : byteRange(req.headers.range, st.size);
+        if (range === 'bad')
+            return send(416, 'range not satisfiable\n', { 'Content-Range': `bytes */${st.size}` });
+        if (range) {
+            const [start, end] = range;
+            headers['Content-Range'] = `bytes ${start}-${end}/${st.size}`;
+            headers['Content-Length'] = String(end - start + 1);
+            res.writeHead(206, headers);
+            if (head)
+                return void res.end();
+            stats.files++;
+            stats.stored += end - start + 1;
+            const src = createReadStream(file, { start, end });
+            src.on('data', (c) => (stats.wire += c.length));
+            void pipeline(src, res).catch(() => res.destroy());
+            return;
+        }
+        const asStored = () => {
+            if (st.size <= streamAbove)
+                return finish(readFileSync(file));
+            headers['Content-Length'] = String(st.size);
+            res.writeHead(200, headers);
+            if (head)
+                return void res.end();
+            stats.files++;
+            stats.stored += st.size;
+            const tap = new Tap(0, (n) => (stats.wire += n));
+            void pipeline(createReadStream(file), tap, res).catch(() => res.destroy());
+        };
+        const enc = live ? pickEncoding('br', req.headers['accept-encoding'], secureRequest(req)) : 'identity';
+        if (enc === 'identity')
+            return asStored();
+        const hit = lookup(file, enc, st);
+        if (hit) {
+            stats.hits++;
+            if (!hit.body)
+                return asStored();
+            headers['Content-Encoding'] = enc;
+            return finish(hit.body, true);
+        }
+        stats.misses++;
+        void (async () => {
+            const small = st.size <= streamAbove;
+            const plain = small ? await readFile(file) : await headOf(file, SAMPLE);
+            if (st.size < 64 || looksCompressed(plain)) {
+                keep(file, enc, st, null);
+                return asStored();
+            }
+            const packed = await pack(plain, enc);
+            const worth = packed.length <= plain.length * WORTH;
+            if (!worth) {
+                keep(file, enc, st, null);
+                return asStored();
+            }
+            headers['Content-Encoding'] = enc;
+            if (small) {
+                keep(file, enc, st, packed);
+                return finish(packed, true);
+            }
+            res.writeHead(200, headers);
+            if (head)
+                return void res.end();
+            stats.files++;
+            stats.stored += st.size;
+            stats.compressed++;
+            const tap = new Tap(cache.cap, (n) => (stats.wire += n), (t) => {
+                const now = statSync(file);
+                if (now.mtimeMs !== st.mtimeMs || now.size !== st.size || t.overflowed)
+                    return;
+                keep(file, enc, st, Buffer.concat(t.chunks));
+            });
+            const z = enc === 'br' ? createBrotliCompress(brParams(st.size)) : createGzip({ level: GZIP_LEVEL });
+            await pipeline(createReadStream(file), z, tap, res);
+        })().catch(() => (res.headersSent ? res.destroy() : send(500, `could not compress ${path}\n`)));
+    };
+    return Object.assign(handler, { stats });
+}
+export function startWebglServer(root, port = DEFAULT_PORT, host = '0.0.0.0', options = {}) {
+    return new Promise((ok, fail) => {
+        const handler = webglHandler(root, options);
+        const server = createServer(handler);
+        server.once('error', fail);
+        server.listen(port, host, () => {
+            server.off('error', fail);
+            const addr = server.address();
+            ok({ server, port: typeof addr === 'object' && addr ? addr.port : port, stats: handler.stats });
+        });
+    });
+}

package/dist/setup/lsp.js

@@ -0,0 +1,42 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { onPath } from "../store/doctor.js";
+export const TS_LSP = 'typescript-language-server@4.3.3';
+const KNOWN = [
+    { id: 'typescript', extensions: { '.ts': 'typescript', '.tsx': 'typescriptreact', '.mts': 'typescript', '.cts': 'typescript', '.js': 'javascript', '.jsx': 'javascriptreact', '.mjs': 'javascript' },
+        find: (_h, p) => (onPath('npx', p) ? { command: onPath('npx', p), args: ['-y', TS_LSP, '--stdio'] } : null), install: 'install Node.js (npx comes with it)' },
+    { id: 'csharp', extensions: { '.cs': 'csharp' },
+        find: (h, p) => { const at = onPath('csharp-ls', p) ?? (existsSync(join(h, '.dotnet', 'tools', 'csharp-ls')) ? join(h, '.dotnet', 'tools', 'csharp-ls') : null); return at ? { command: at } : null; },
+        install: 'dotnet tool install -g csharp-ls' },
+    { id: 'swift', extensions: { '.swift': 'swift' },
+        find: (_h, p) => { const at = onPath('sourcekit-lsp', p) ?? xcrun('sourcekit-lsp'); return at ? { command: at } : null; }, install: 'install Xcode (sourcekit-lsp comes with it)' },
+    { id: 'python', extensions: { '.py': 'python', '.pyi': 'python' },
+        find: (_h, p) => { const at = onPath('pyright-langserver', p) ?? onPath('basedpyright-langserver', p); return at ? { command: at, args: ['--stdio'] } : null; }, install: 'npm install -g pyright' },
+    { id: 'go', extensions: { '.go': 'go' }, find: (_h, p) => (onPath('gopls', p) ? { command: onPath('gopls', p) } : null), install: 'go install golang.org/x/tools/gopls@latest' },
+    { id: 'rust', extensions: { '.rs': 'rust' }, find: (_h, p) => (onPath('rust-analyzer', p) ? { command: onPath('rust-analyzer', p) } : null), install: 'rustup component add rust-analyzer' },
+    { id: 'cpp', extensions: { '.c': 'c', '.h': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.hpp': 'cpp', '.m': 'objective-c', '.mm': 'objective-cpp' },
+        find: (_h, p) => { const at = onPath('clangd', p) ?? xcrun('clangd'); return at ? { command: at } : null; }, install: 'xcode-select --install (clangd comes with the command line tools)' },
+];
+function xcrun(tool) {
+    try {
+        const r = spawnSync('xcrun', ['--find', tool], { encoding: 'utf8', timeout: 5000 });
+        const at = r.status === 0 ? r.stdout.trim() : '';
+        return at && existsSync(at) ? at : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function languageServers(home, path = process.env.PATH ?? '') {
+    const servers = {};
+    const missing = [];
+    for (const k of KNOWN) {
+        const found = k.find(home, path);
+        if (found)
+            servers[k.id] = { command: found.command, ...(found.args ? { args: found.args } : {}), extensionToLanguage: k.extensions };
+        else
+            missing.push({ id: k.id, install: k.install });
+    }
+    return { servers, missing };
+}

package/dist/sim/curve.js

@@ -0,0 +1,122 @@
+import { byRole } from "./judge.js";
+export const FLAT_SECONDS = 45;
+export const WALL_SHARE = 0.25;
+export const HUMAN_SHARE = 0.5;
+export const LOSABLE_SECONDS = 60;
+const share = (n, of) => (of > 0 ? (n ?? 0) / of : 0);
+const pct = (x) => `${Math.round(100 * x)}%`;
+const mmss = (s) => { const r = Math.round(s); return `${Math.floor(r / 60)}:${String(r % 60).padStart(2, '0')}`; };
+const at = (c, level) => c?.levels?.find((l) => l.level === level);
+const split = (c) => !!c?.levels?.some((l) => typeof l.cleared === 'number');
+export function curveRows(cohorts) {
+    const players = [byRole(cohorts, 'naive'), byRole(cohorts, 'novice'), byRole(cohorts, 'skilled'), cohorts.find((c) => c.role === 'skilled' && c.human)].filter((c) => !!c && split(c));
+    const levels = [...new Set(players.flatMap((c) => c.levels.map((l) => l.level)))].sort((a, b) => a - b);
+    return levels.map((lv) => `level ${lv}: ${players.map((c) => {
+        const l = at(c, lv);
+        return `${c.human ? `skilled@${c.human.hz}hz` : c.role} ${l ? `clears ${pct(share(l.cleared, l.reached))}, loses ${pct(share(l.lost, l.reached))}, ${mmss(l.meanSeconds ?? 0)} there (${l.reached} reached)` : 'never reached'}`;
+    }).join(' · ')}`);
+}
+export function judgeCurve(cohorts) {
+    const out = [];
+    const skilled = byRole(cohorts, 'skilled');
+    const human = cohorts.find((c) => c.role === 'skilled' && c.human);
+    const measured = ['naive', 'novice', 'skilled'].map((r) => byRole(cohorts, r)).filter((c) => !!c && split(c));
+    const played = cohorts.filter((c) => c.seeds > 0);
+    if (played.length && played.every((c) => c.lost === 0) && played.some((c) => c.seconds >= LOSABLE_SECONDS)) {
+        out.push({ id: 'losable', state: 'warn', says: `no run was lost by any of ${played.length} players over ${played[0].seeds} seeds (${played.map((c) => c.policy).join(', ')}): a run cannot be lost`, next: 'a puzzle or a toy on purpose? say so in the design doc and to the player; else a threat, a clock or a resource that can end a run' });
+    }
+    if (!measured.length) {
+        out.push({ id: 'curve', state: 'not measured', says: skilled?.levels?.length ? 'the probe keeps when levels were reached but not who cleared or lost them (an older src/probe-kit.ts: funtools upgrade parks the new one)' : 'no level(run) in test/probes.ts: the difficulty curve per level, stage or wave was never split', next: 'add level(run) to the probe game (the level, stage or wave number) so sim splits clear rate, loss rate and time per level' });
+    }
+    else {
+        const levels = [...new Set(measured.flatMap((c) => c.levels.map((l) => l.level)))].sort((a, b) => a - b);
+        for (const lv of levels) {
+            const rows = measured.map((c) => at(c, lv)).filter((l) => !!l && l.reached > 0);
+            if (rows.length === measured.length && rows.every((l) => share(l.cleared, l.reached) >= 0.95 && !l.lost && (l.meanSeconds ?? 0) < FLAT_SECONDS)) {
+                const slowest = Math.max(...rows.map((l) => l.meanSeconds ?? 0));
+                out.push({ id: `flat:${lv}`, state: lv === levels[0] ? 'note' : 'warn', says: `level ${lv} is flat: every player (${measured.map((c) => c.role).join(', ')}) clears it, none loses, the slowest in ${mmss(slowest)}`, next: lv === levels[0] ? 'a first level may teach; if it only teaches, say so and keep it short; else give it one idea to learn and a way to fail' : 'a breather is a choice; a flat level in the middle of the ramp is time with nothing to learn: a new idea, a threat, a tighter clock or a star worth chasing' });
+            }
+            const s = at(skilled, lv), h = at(human, lv);
+            const sClear = s && s.reached ? share(s.cleared, s.reached) : null, hClear = h && h.reached ? share(h.cleared, h.reached) : null;
+            if (sClear !== null && hClear !== null && sClear >= 0.5 && hClear < HUMAN_SHARE * sClear) {
+                out.push({ id: `wall:${lv}`, state: 'warn', says: `level ${lv} is a wall for people: the skilled bot clears it on ${pct(sClear)} of seeds at 60 decisions a second, but ${pct(hClear)} at ${human.human.hz} a second with ${human.human.reactMs} ms to react`, next: 'the level asks for superhuman input (one race, 30 Sep): longer warnings, a wider window, fewer inputs per second, or a slower rival' });
+            }
+            else if ((hClear ?? sClear) !== null && (hClear ?? sClear) < WALL_SHARE && ((h ?? s).lost ?? 0) > 0 && lv !== levels.at(-1)) {
+                const who = h ? `the skilled player at ${human.human.hz} decisions a second` : 'the skilled bot';
+                out.push({ id: `wall:${lv}`, state: 'warn', says: `level ${lv} is a wall: ${who} clears it on ${pct((hClear ?? sClear))} of the ${(h ?? s).reached} seeds that reach it`, next: 'a step up that stops a good player is a wall, not a ramp: split it, add a checkpoint, or teach its idea on the level before' });
+            }
+        }
+        const ramp = byRole(cohorts, 'novice') ?? byRole(cohorts, 'naive');
+        const lvs = (ramp?.levels ?? []).filter((l) => l.reached >= 3);
+        if (ramp && lvs.length >= 3 && split(ramp)) {
+            const half = Math.floor(lvs.length / 2), avg = (xs) => xs.reduce((a, b) => a + b, 0) / (xs.length || 1);
+            const loss = (l) => share(l.lost, l.reached), time = (l) => l.meanSeconds ?? 0;
+            const rises = avg(lvs.slice(-half).map(loss)) > avg(lvs.slice(0, half).map(loss)) || avg(lvs.slice(-half).map(time)) > 1.2 * avg(lvs.slice(0, half).map(time));
+            const shape = lvs.map((l) => `${l.level} ${pct(loss(l))}/${mmss(time(l))}`).join(' · ');
+            out.push(rises
+                ? { id: 'ramp', state: 'ok', says: `the ${ramp.role} player's loss rate and time per level rise across the run (${shape})` }
+                : { id: 'ramp', state: 'note', says: `no ramp: the ${ramp.role} player loses no more and takes no longer on later levels than early ones (${shape})`, next: 'a ramp with breathers: each level a little harder than the last, a calmer one after a spike, the hardest near the end (references/escalation.md)' });
+        }
+    }
+    out.push(...judgeLoss(cohorts));
+    if (skilled && !human)
+        out.push({ id: 'human-rate', state: 'not measured', says: `no skilled player at a human rate: the sharp bot (${skilled.says}) may press faster than a thumb can, so a wall for people reads as a pass`, next: 'add humanRate(skilled, game.dt, { rest: <no press> }) from src/probe-human.ts beside it: 12 decisions a second, 200 ms to react' });
+    return out;
+}
+export const carefulAtHumanPace = (cohorts) => cohorts.filter((c) => c.human && (c.role === 'skilled' || c.role === 'taught'));
+const human = (c) => !c.foresight;
+const who = (c) => `${c.policy} (the ${c.role === 'skilled' ? 'sharp' : c.role} policy${c.human ? ` at ${c.human.hz} decisions a second, ${c.human.reactMs} ms to react` : ''}${c.foresight ? `; FORESIGHT: ${c.foresight}` : ''}) ${c.won}/${c.seeds}`;
+export function judgeLoss(cohorts) {
+    const out = [];
+    const naive = byRole(cohorts, 'naive');
+    const played = cohorts.filter((c) => c.seeds > 0);
+    const nobodyLoses = played.length > 0 && played.every((c) => c.lost === 0);
+    if (!naive)
+        out.push({ id: 'naive-loses', state: 'not measured', says: 'no naive policy: whether steering straight at the goal can lose was never played' });
+    else if (naive.lost > 0)
+        out.push({ id: 'naive-loses', state: 'ok', says: `the naive player (${naive.says}) loses ${naive.lost} of ${naive.seeds} runs` });
+    else if (!nobodyLoses)
+        out.push({ id: 'naive-loses', state: 'warn', says: `the naive player (${naive.says}) never loses a run in ${naive.seeds} seeds: steering straight at the goal is safe`, next: 'a hazard on the straight line that ends the run (caught, fallen, out of time, wrecked) and a retry from a checkpoint; penalties such as lost time, charge or score are not a loss' });
+    const careful = carefulAtHumanPace(cohorts);
+    if (careful.length) {
+        const winners = careful.filter((c) => c.won > 0);
+        const people = winners.filter(human);
+        const taught = byRole(cohorts, 'taught');
+        const teachNote = taught && taught.seeds > 0 && taught.won / taught.seeds < 0.5 && !winners.includes(taught) ? `; the taught policy ${taught.policy} wins ${taught.won}/${taught.seeds}` : '';
+        if (!winners.length)
+            out.push({ id: 'human-win', state: 'warn', says: `at a human pace nobody wins with the default settings: ${careful.map((c) => `${c.policy} ${c.won}/${c.seeds} (${c.lost} lost)`).join(', ')}`, next: 'the challenge must bite the careless and let the careful through: longer tells, a wider window, a checkpoint, or a gentler default before any assist' });
+        else if (!people.length)
+            out.push({ id: 'human-win', state: 'warn', says: `only a policy that looks ahead wins at a human pace: ${winners.map(who).join(', ')}${teachNote}`, next: 'a person cannot clone the run or see seconds ahead: give the danger a tell a player can read in time (a beat, a sweep that shows where it goes), then a human-pace policy that reads only the tell must win' });
+        else
+            out.push({ id: 'human-win', state: 'ok', says: `at a human pace, with the defaults: ${people.map(who).join(', ')} wins${teachNote}`, ...(teachNote ? { next: 'the winner is the sharp policy, not the taught one: if it reads more than the game shows (it simulates ahead, clones the run), mark it foresight in test/probes.ts' } : {}) });
+    }
+    out.push(...judgeMiddle(cohorts));
+    return out;
+}
+export function judgeMiddle(cohorts) {
+    const naive = byRole(cohorts, 'naive'), middle = byRole(cohorts, 'middle');
+    const top = [byRole(cohorts, 'taught'), ...carefulAtHumanPace(cohorts)].filter((c) => !!c && c.seeds > 0).sort((a, b) => b.won / b.seeds - a.won / a.seeds)[0];
+    if (!naive || !top || naive.seeds === 0)
+        return [];
+    const gap = top.won / top.seeds - naive.won / naive.seeds;
+    if (!middle)
+        return gap >= 0.5 ? [{ id: 'middle', state: 'not measured', says: `no middle policy: the naive player wins ${naive.won}/${naive.seeds} and ${top.policy} ${top.won}/${top.seeds} — whether doing half of what is taught pays (a ramp) or loses like doing nothing (a cliff) was never played`, next: "add { name: 'middle', role: 'middle', says: '<some of the lesson: leans and rests, never takes cover>', make } to test/probes.ts" }] : [];
+    const m = middle.won / Math.max(1, middle.seeds), n = naive.won / naive.seeds;
+    if (gap >= 0.3 && m <= n + 0.1)
+        return [{ id: 'middle', state: 'note', says: `a difficulty cliff: the middle player (${middle.says}) wins ${middle.won}/${middle.seeds}, like the naive one (${naive.won}/${naive.seeds}), while ${top.policy} wins ${top.won}/${top.seeds}`, next: 'nothing between careless and careful pays: let each part of the lesson help on its own (leaning alone gets further, resting alone survives longer), so a player learning it sees progress' }];
+    return [{ id: 'middle', state: 'ok', says: `a ramp: the middle player (${middle.says}) wins ${middle.won}/${middle.seeds}, between the naive ${naive.won}/${naive.seeds} and ${top.policy} ${top.won}/${top.seeds}` }];
+}
+export function judgeReach(cohorts, claimed, where = 'the design doc') {
+    if (!claimed || claimed < 2)
+        return null;
+    const skilled = byRole(cohorts, 'skilled');
+    const reached = (skilled?.levels ?? []).filter((l) => l.reached > 0).map((l) => l.level);
+    if (!skilled || !reached.length)
+        return { id: 'reach', state: 'not measured', says: `${where} claims ${claimed} areas or levels; the probe names no level(run), so how many play reaches is unknown` };
+    const top = Math.max(...reached), won = skilled.won > 0;
+    if (won && top >= claimed)
+        return { id: 'reach', state: 'ok', says: `the skilled bot plays through all ${claimed} areas ${where} claims` };
+    if (top <= claimed / 2)
+        return { id: 'reach', state: 'warn', says: `${where} claims ${claimed} areas or levels; the skilled bot reaches ${top}`, next: 'play reaches much less than the plan claims (one game claimed 8 worlds, play reached 2): build and wire what the plan names, lower the claim, or fix the wall that stops the bot' };
+    return { id: 'reach', state: 'note', says: `${where} claims ${claimed} areas or levels; the skilled bot reaches ${top}${won ? '' : ' and never wins'}` };
+}