@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/look-hud.js

@@ -0,0 +1,180 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { launch, lookPage, viewportUrl } from "../verify/browser.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { drive, evalJson, load, openTarget } from "../look/look.js";
+import { decodePng, encodePng } from "../look/png.js";
+import { desktopTouchFindings, judgeHud, outline, sampleFindings, settle, textContrast } from "../look/hud.js";
+import { uiStyle } from "../look/ui-style.js";
+const TITLE_VIEW = /^(title|menu|start)$/i;
+const MENU_OVER_PLAY = new Set(['cover', 'centre', 'over_player']);
+import { judgePhonePlay, probeSwipe, playArea, bandBoard, SAFARI_PORTRAIT } from "../look/phone-play.js";
+import { viewportLabel } from "./look.js";
+import { ui } from "../ui.js";
+export const HUD_SAMPLING = { samples: 8, everyMs: 500, max: 24 };
+async function sampleView(page, url, manifest, view, opts, probe) {
+    await load(page, url, hookMapOf(manifest));
+    const driven = await drive(page, { view, verbs: opts.verbs, holdMs: 600, freeze: false, click: opts.click });
+    if (driven.view?.entered !== true)
+        return { samples: [], frames: [], phone: [], swipe: null, safari: null, entered: false, error: driven.view?.error || 'the page refused' };
+    const decl = manifest.actors ?? {};
+    const samples = [], frames = [], phone = [];
+    const t0 = Date.now();
+    for (let i = 0; i < opts.samples; i++) {
+        const started = Date.now();
+        const hud = await evalJson(page, 'hud', { max: 60 });
+        const actors = await evalJson(page, 'actors', { player: decl.player ?? '', threats: decl.threats ?? '', max: 20 });
+        frames.push(await page.screenshot({ type: 'png', scale: 'css' }));
+        samples.push({ at_ms: started - t0, view, play: hud?.play ?? null, viewport: hud?.viewport ?? { w: 0, h: 0 }, pieces: hud?.pieces ?? [], actors: actors?.actors ?? [], touch_controls: hud?.touch_controls ?? [] });
+        phone.push({ board: hud?.board ?? null, pad: hud?.pad ?? [], gestures: hud?.gestures ?? [] });
+        await new Promise((r) => setTimeout(r, Math.max(0, opts.everyMs - (Date.now() - started))));
+    }
+    let swipe = null, safari = null;
+    if (probe) {
+        const size = page.viewportSize();
+        if (size && size.height > size.width) {
+            await page.setViewportSize({ width: SAFARI_PORTRAIT.w, height: SAFARI_PORTRAIT.h });
+            await new Promise((r) => setTimeout(r, 700));
+            const hud = await evalJson(page, 'hud', { max: 60 });
+            if (hud)
+                safari = { sample: { at_ms: 0, view, play: hud.play ?? null, viewport: hud.viewport, pieces: hud.pieces ?? [], actors: [] }, phone: { board: hud.board ?? null, pad: hud.pad ?? [], gestures: hud.gestures ?? [] }, frame: await page.screenshot({ type: 'png', scale: 'css' }) };
+        }
+        const last = safari?.phone ?? phone[phone.length - 1];
+        if (last && (last.pad.length >= 2 || last.gestures.length > 0)) {
+            const area = safari ? (playArea([safari.sample], [safari.phone])?.board ?? bandBoard(safari.sample)) : (playArea(samples, phone)?.board ?? (samples.length ? bandBoard(samples[samples.length - 1]) : null));
+            swipe = area ? await probeSwipe(page, area) : { moved: null, direction: null, note: 'no play area to swipe on' };
+        }
+        if (size)
+            await page.setViewportSize(size);
+    }
+    return { samples, frames, phone, swipe, safari, entered: true };
+}
+async function judgeView(dir, label, view, sampled, frames, phoneSamples, swipe, safari = null) {
+    const samples = settle(sampled);
+    const findings = [];
+    const scaleOf = (s, img) => (s.viewport.w > 0 ? img.width / s.viewport.w : 1);
+    samples.forEach((s, i) => {
+        const img = decodePng(frames[i]);
+        const contrasts = new Map(s.pieces.map((p) => [p, textContrast(img, p, scaleOf(s, img))]));
+        findings.push(sampleFindings(s, i, contrasts).filter((f) => !TITLE_VIEW.test(view) || !MENU_OVER_PLAY.has(f.kind)));
+    });
+    const verdict = judgeHud(samples, findings);
+    const phone = phoneSamples ? judgePhonePlay(samples, phoneSamples, swipe, safari) : null;
+    if (phone) {
+        verdict.findings = [...verdict.findings.filter((f) => f.severity === 'fail'), ...phone.findings, ...verdict.findings.filter((f) => f.severity !== 'fail')];
+        Object.assign(verdict.numbers, { play_area_share: phone.facts.play_area_share, play_fill: phone.facts.play_fill, pad_band_share: phone.facts.pad_band_share });
+    }
+    const score = findings.map((fs) => fs.filter((f) => f.severity === 'fail').length * 10 + fs.length);
+    const worst = score.indexOf(Math.max(...score, 0));
+    let frame;
+    if (samples[worst]) {
+        const s = samples[worst];
+        const board = phoneSamples?.[worst]?.board;
+        const boxes = [...s.pieces.map((p) => ({ ...p, rgb: [255, 0, 200] })), ...s.actors.map((a) => ({ ...a, rgb: [0, 220, 90] })),
+            ...(board ? [{ ...board, rgb: [0, 200, 255] }] : [])];
+        frame = join(dir, '.funtools', 'look', `hud-${view}-${label}.png`);
+        const img = decodePng(frames[worst]);
+        await writeFile(frame, encodePng(outline(img, boxes, scaleOf(s, img))));
+    }
+    let safariFrame;
+    if (phone && safari) {
+        const img = decodePng(safari.frame);
+        const board = safari.phone.board;
+        const boxes = [...safari.sample.pieces.map((p) => ({ ...p, rgb: [255, 0, 200] })), ...(board ? [{ ...board, rgb: [0, 200, 255] }] : [])];
+        safariFrame = join(dir, '.funtools', 'look', `hud-${view}-${label}-safari.png`);
+        await writeFile(safariFrame, encodePng(outline(img, boxes, scaleOf(safari.sample, img))));
+    }
+    return { view, entered: true, samples: samples.length, frame, ...(safariFrame ? { safari_frame: safariFrame } : {}), ...verdict, ...(phone ? { phone: phone.facts } : {}) };
+}
+export async function lookHud(opts, io = console) {
+    const u = ui(io, 'look');
+    const t = await openTarget(opts.target ?? '.');
+    if (typeof t === 'string') {
+        u.error(t, 'build the game first (npm run build)');
+        return EXIT.error;
+    }
+    const dir = t.dir ?? resolve('.');
+    const label = viewportLabel(opts, t.manifest);
+    const results = [];
+    let titleUi = null;
+    const played = [];
+    let browser;
+    try {
+        browser = (await launch()).browser;
+        const orientation = opts.orientation ?? (typeof t.manifest.metadata?.orientation === 'string' ? t.manifest.metadata.orientation : '');
+        const page = await lookPage(browser, opts.viewport, orientation);
+        const url = viewportUrl(t.url, opts.viewport);
+        await load(page, url, hookMapOf(t.manifest));
+        const declared = (await evalJson(page, 'capture_view', { view: null, verbs: [], verb_gap_ms: 0, hold_ms: 0, freeze: false }))?.views ?? [];
+        const names = opts.view ? [opts.view] : [...new Set([declared.some((v) => v.name === 'playing') ? 'playing' : declared[0]?.name, ...declared.filter((v) => v.moment).map((v) => v.name)].filter(Boolean))];
+        if (!names.length) {
+            u.error('the game declares no views', 'declare __FPX_VIEWS__ with a playing view (skill funpixel-verify)');
+            return EXIT.not_observed;
+        }
+        await mkdir(join(dir, '.funtools', 'look'), { recursive: true });
+        const phone = opts.viewport === 'phone' && !(opts.view && TITLE_VIEW.test(opts.view));
+        for (const [i, view] of names.entries()) {
+            const r = await sampleView(page, url, t.manifest, view, opts, phone && i === 0);
+            played.push(...r.samples);
+            const judged = r.entered ? await judgeView(dir, label, view, r.samples, r.frames, phone && i === 0 ? r.phone : null, r.swipe, r.safari) : { view, entered: false, error: r.error, samples: 0, verdict: 'not_observed', findings: [], numbers: {} };
+            if (r.entered && opts.viewport === 'desktop' && !TITLE_VIEW.test(view))
+                judged.findings.push(...desktopTouchFindings(r.samples));
+            results.push(judged);
+        }
+        const title = opts.view ? undefined : declared.find((v) => TITLE_VIEW.test(v.name) && !names.includes(v.name))?.name;
+        if (title) {
+            await load(page, url, hookMapOf(t.manifest));
+            const driven = await drive(page, { view: title, verbs: [], holdMs: 600, freeze: false, click: null });
+            const hud = driven.view?.entered === true ? await evalJson(page, 'hud', { max: 60 }) : null;
+            if (hud)
+                titleUi = uiStyle([{ at_ms: 0, view: title, play: hud.play ?? null, viewport: hud.viewport, pieces: hud.pieces ?? [], actors: [] }], title, true);
+        }
+    }
+    catch (e) {
+        u.error(`look --hud failed: ${e instanceof Error ? e.message : String(e)}`);
+        return EXIT.error;
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        await t.close();
+    }
+    const titleAsked = !!opts.view && TITLE_VIEW.test(opts.view);
+    if (titleAsked && played.length)
+        titleUi = uiStyle(played, opts.view, true);
+    const playUi = played.length && !titleAsked ? uiStyle(played, 'play') : null;
+    const verdict = results.some((r) => r.verdict === 'fail') ? 'fail' : results.some((r) => r.verdict === 'pass') ? 'pass' : 'not_observed';
+    const phonePlay = results.find((r) => r.phone)?.phone ?? null;
+    const record = { verdict, viewport: label, ...(phonePlay ? { play_area_share: phonePlay.play_area_share, play_fill: phonePlay.play_fill, controls_duplicate_gesture: phonePlay.controls_duplicate_gesture, phone_play: phonePlay } : {}), views: results, ...(playUi || titleUi ? { ui_style: { ...(playUi ? { play: playUi } : {}), ...(titleUi ? { title: titleUi } : {}) } } : {}), at: new Date().toISOString() };
+    await writeFile(join(dir, '.funtools', 'look', `hud-${label}.json`), JSON.stringify(record, null, 2) + '\n').catch(() => { });
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return EXIT[verdict];
+    }
+    u.heading(`look --hud · ${label}`);
+    for (const r of results) {
+        if (!r.entered) {
+            u.item('not_observed', `${r.view}: not entered`, r.error);
+            continue;
+        }
+        const n = r.numbers;
+        u.item(r.verdict, `${r.view}: ${r.samples} samples · cover up to ${Math.round(Number(n.cover_max ?? 0) * 100)}% · smallest text ${n.smallest_text_px ?? '—'} px · transient at once up to ${n.transient_max ?? 0}${n.player_covered_share != null ? ` · HUD over the player in ${Math.round(Number(n.player_covered_share) * 100)}% of samples` : ''}`, r.frame);
+        if (r.phone) {
+            const p = r.phone;
+            u.item('note', `play on the phone: ${p.play_area_share == null ? 'not measured' : `${Math.round(p.play_area_share * 100)}% of a ${p.measured_at?.w}x${p.measured_at?.h} page, ${Math.round(Number(p.play_fill) * 100)}% of what fits (${p.board_source})`}${p.pad_keys.length ? ` · pad ${p.pad_keys.join(' ')} claims ${Math.round(Number(p.pad_band_share) * 100)}% of the height` : ' · no direction pad'}${p.idle_rows_share != null ? ` · ${Math.round(p.idle_rows_share * 100)}% of the height neither play nor readout` : ''}${p.swipe.tried || p.swipe.claimed_by_play ? ` · ${p.swipe.claimed_by_play ? 'the play claims the pad\'s keys' : p.swipe.note}` : ''}`, r.safari_frame ? `as Safari shows it (bars take 160 px of the height): ${r.safari_frame}` : undefined);
+        }
+        for (const f of r.findings.slice(0, 8))
+            u.item(f.severity, `${f.where}: ${f.what}`);
+        if (r.verdict === 'not_observed')
+            u.item('note', 'no HUD piece seen: a HUD drawn in a Three canvas or a WebGL texture is invisible to this measure');
+    }
+    for (const [name, st] of [['play', playUi], ['title', titleUi]]) {
+        if (!st)
+            continue;
+        u.item('note', `${name} dressing: ${st.system_type_share === null ? 'no text read' : `${Math.round(st.system_type_share * 100)}% of texts in the system stack`} · ${st.default_plates} of ${st.plates} plates flat dark fills · ${st.stock_glyphs.length} scaffold glyphs${st.text_glyphs?.length ? ` · ${st.text_glyphs.length} typed glyphs (${st.text_glyphs.join(' ')})` : ''}${st.wordmark ? ` · wordmark ${st.wordmark.art ? 'as art' : st.wordmark.system ? 'in the system stack' : 'in its own face'}` : ''}`);
+        for (const f of st.findings)
+            u.item(f.severity, `${f.where}: ${f.what}`);
+    }
+    u.summary(verdict, verdict === 'pass' ? 'the HUD keeps to its zone and reads on the frame' : verdict === 'fail' ? 'the HUD gets in the way — see the outlined frame' : 'nothing measured — never read as a pass');
+    return EXIT[verdict];
+}

package/dist/commands/look-read.js

@@ -0,0 +1,162 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { launch, viewportOptions } from "../verify/browser.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { drive, evalJson, load, openTarget } from "../look/look.js";
+import { decodePng } from "../look/png.js";
+import { boxContrast, colourContrast, judgeRoles, parseHex, READ_MIN_DELTA_E, } from "../look/readability.js";
+import { ui } from "../ui.js";
+export function roleColours(dir, flag) {
+    const out = {};
+    if (flag) {
+        for (const part of flag.split(',')) {
+            const [k, v] = part.split('=').map((s) => s.trim());
+            const c = v ? parseHex(v) : null;
+            if (c && (k === 'player' || k === 'threat'))
+                out[k] = c;
+        }
+        return out;
+    }
+    const path = dir && join(dir, 'assets', 'style.json');
+    if (!path || !existsSync(path))
+        return out;
+    try {
+        const roles = JSON.parse(readFileSync(path, 'utf8')).roles ?? {};
+        const pick = (...keys) => keys.map((k) => (typeof roles[k] === 'string' ? parseHex(roles[k]) : null)).find(Boolean) ?? undefined;
+        const p = pick('hero', 'player'), t = pick('harm', 'threat', 'enemy');
+        if (p)
+            out.player = p;
+        if (t)
+            out.threat = t;
+    }
+    catch { }
+    return out;
+}
+const HOW = { tag: 'by role tag', declared: 'by the declared pattern', words: 'by the usual words' };
+export function matchedLines(m) {
+    return ['player', 'threat'].flatMap((role) => {
+        const r = m[role];
+        if (!r)
+            return [];
+        const took = r.names.length ? `${r.names.join(', ')}${r.count > r.names.length ? ` (${r.count} nodes)` : ''}` : 'nothing on screen';
+        const hint = r.by === 'words' && r.names.length ? ` — not the actor? name its root node ${role}-… (skill funpixel-verify)` : '';
+        return [`${role} ${HOW[r.by] ?? r.by}: ${took}${hint}`];
+    });
+}
+export function hiddenLines(hidden, measuredRoles, occlusion) {
+    const out = [];
+    for (const role of ['player', 'threat']) {
+        const h = hidden.filter((x) => x.role === role);
+        if (!h.length)
+            continue;
+        const names = [...new Set(h.map((x) => x.name))].slice(0, 6).join(', ');
+        const all = !measuredRoles.includes(role);
+        out.push([all ? 'not_observed' : 'note', `${h.length} ${role === 'player' ? 'player' : 'threat'} actor(s) hidden from this camera (behind a wall, a door, or off screen), not measured: ${names}`,
+            all ? `none in view: hold a view where a ${role} stands in the open (a __FPX_VIEWS__ entry, or --view), then read again` : undefined]);
+    }
+    if (occlusion === 'not_observed')
+        out.push(['note', 'occlusion not tested: the scene was too big to ray in time, so every matched actor was boxed, seen or not', undefined]);
+    return out;
+}
+function byColour(img, colours) {
+    const out = [];
+    for (const role of ['player', 'threat']) {
+        const c = colours[role];
+        const m = c && colourContrast(img, c);
+        if (m)
+            out.push({ role, name: `colour ${role}`, contrast: m });
+    }
+    return out;
+}
+export async function lookRead(opts, io = console) {
+    const u = ui(io, 'look');
+    const target = opts.target ?? '.';
+    let img, source, actors = [], names = [], engine = 'none', view = null, file;
+    let matched = {};
+    let hidden = [], occlusion = 'none';
+    let dir = null;
+    if (/\.png$/i.test(target)) {
+        file = resolve(target);
+        img = decodePng(await readFile(file));
+        source = 'colours';
+    }
+    else {
+        const t = await openTarget(target);
+        if (typeof t === 'string') {
+            u.error(t, 'build the game first (npm run build)');
+            return EXIT.error;
+        }
+        dir = t.dir;
+        let browser;
+        try {
+            browser = (await launch()).browser;
+            const orientation = typeof t.manifest.metadata?.orientation === 'string' ? t.manifest.metadata.orientation : '';
+            const page = await (await browser.newContext(viewportOptions(opts.viewport, orientation))).newPage();
+            await load(page, t.url, hookMapOf(t.manifest));
+            const declared = ((await evalJson(page, 'capture_view', { view: null, verbs: [], verb_gap_ms: 0, hold_ms: 0, freeze: false }))?.views ?? []).map((v) => v.name);
+            view = opts.view ?? (declared.includes('playing') ? 'playing' : null);
+            const driven = await drive(page, { view, verbs: [], holdMs: opts.holdMs, freeze: true, click: opts.click });
+            if (view && driven.view?.entered !== true) {
+                u.error(`could not enter the view "${view}"`, driven.view?.error || 'declare it in __FPX_VIEWS__ (skill funpixel-verify)');
+                return EXIT.not_observed;
+            }
+            const decl = t.manifest.actors ?? {};
+            const a = await evalJson(page, 'actors', { player: opts.player ?? decl.player ?? '', threats: opts.threats ?? decl.threats ?? '', max: 40 });
+            actors = a?.actors ?? [];
+            names = a?.names ?? [];
+            matched = a?.matched ?? {};
+            engine = a?.engine ?? 'none';
+            hidden = a?.hidden ?? [];
+            occlusion = a?.occlusion ?? 'none';
+            const png = await page.screenshot({ type: 'png', scale: 'css' });
+            file = join(dir ?? resolve('.'), '.funtools', 'look', `read-${view ?? 'as-loaded'}-${opts.viewport}.png`);
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, png);
+            img = decodePng(png);
+            source = actors.length ? 'boxes' : 'colours';
+        }
+        finally {
+            await browser?.close().catch(() => { });
+            await t.close();
+        }
+    }
+    const measured = source === 'boxes'
+        ? actors.flatMap((a) => { const c = boxContrast(img, a); return c ? [{ role: a.role, name: a.name, contrast: c, box: a }] : []; })
+        : byColour(img, roleColours(dir ?? (/\.png$/i.test(target) ? resolve('.') : null), opts.colours));
+    const heights = (role) => measured.filter((m) => m.role === role && m.box).map((m) => m.box.h).sort((a, b) => a - b);
+    const roles = judgeRoles(measured).map((r) => {
+        const h = heights(r.role);
+        return h.length ? { ...r, height_px: h[h.length >> 1], height_share: Math.round((h[h.length >> 1] / img.height) * 1000) / 1000 } : r;
+    });
+    const verdict = !roles.length ? 'not_observed' : roles.every((r) => r.pass) ? 'pass' : 'fail';
+    const result = {
+        verdict, min_delta_e: READ_MIN_DELTA_E, source, engine, view, viewport: opts.viewport, file, size: `${img.width}x${img.height}`,
+        roles, ...(Object.keys(matched).length ? { matched } : {}), occlusion, hidden, actors: measured.map((m) => ({ role: m.role, name: m.name, ...m.contrast, ...(m.box ? { box: { x: m.box.x, y: m.box.y, w: m.box.w, h: m.box.h } } : {}) })),
+        ...(source === 'colours' && engine !== 'none' ? { names_seen: names.slice(0, 20) } : {}),
+    };
+    if (dir)
+        await writeFile(join(dir, '.funtools', 'look', `read-${view ?? 'as-loaded'}-${opts.viewport}.json`), JSON.stringify(result, null, 2) + '\n').catch(() => { });
+    if (opts.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return EXIT[verdict];
+    }
+    u.heading(`look --read · ${view ?? 'as loaded'} · ${opts.viewport} · ${source === 'boxes' ? `${engine} boxes` : 'role colours'}`);
+    for (const line of matchedLines(matched))
+        u.line(line);
+    for (const line of hiddenLines(hidden, roles.map((r) => r.role), occlusion))
+        u.item(line[0], line[1], line[2]);
+    for (const r of roles) {
+        const size = 'height_px' in r ? `, ${r.height_px} px tall (${Math.round(r.height_share * 100)}% of the screen)` : '';
+        u.item(r.pass ? 'pass' : 'fail', `${r.role}: ΔE ${r.delta_e} against its ground (ΔL ${r.delta_l}), ${r.measured} measured${size}`, r.pass ? undefined : `the bar is ΔE ${READ_MIN_DELTA_E}; weakest ${r.weakest?.name} at ${r.weakest?.delta_e}: add an outline, a rim or a value step (skill funpixel-art)`);
+    }
+    if (!roles.length && !hidden.length) {
+        u.item('not_observed', 'no player or threat found', engine !== 'none'
+            ? `name the actors' root nodes player-… and threat-… (or userData.role), or give funpixel.json "actors": { "player": "<regex>", "threats": "<regex>" } — nodes seen: ${names.slice(0, 8).join(', ') || 'none named'}`
+            : 'expose the scene (window.__PIXI_APP__, or __THREEJS_SCENE__ + camera), or give role colours in assets/style.json');
+    }
+    u.line(file);
+    u.summary(verdict, verdict === 'pass' ? 'the actors read against the ground' : verdict === 'fail' ? 'an actor merges with its ground' : 'nothing measured — never read as a pass');
+    return EXIT[verdict];
+}

package/dist/commands/look-sheet.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { decodePng, encodePng } from "../look/png.js";
+import { parseHex, READ_MIN_DELTA_E } from "../look/readability.js";
+import { composeSheet, crop, NEUTRAL, SHEET_SIZES, trim } from "../look/sheet.js";
+import { sheetLoops } from "../look/loops.js";
+import { ui } from "../ui.js";
+import { patchBoard } from "../status/board.js";
+const MAX_SPRITES = 60;
+export function groundColour(dir, flag) {
+    if (flag) {
+        const c = parseHex(flag);
+        return c ? { rgb: c, from: '--ground' } : null;
+    }
+    const path = join(dir, 'assets', 'style.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const roles = JSON.parse(readFileSync(path, 'utf8')).roles ?? {};
+        for (const k of ['ground', 'floor', 'surface', 'background']) {
+            const c = typeof roles[k] === 'string' ? parseHex(roles[k]) : null;
+            if (c)
+                return { rgb: c, from: `assets/style.json roles.${k}` };
+        }
+    }
+    catch { }
+    return null;
+}
+const manifestOf = (png) => {
+    try {
+        return JSON.parse(readFileSync(png.replace(/\.png$/i, '.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+export function atlasFrame(png) {
+    try {
+        const frames = manifestOf(png)?.frames;
+        const [name, f] = Array.isArray(frames) ? [frames[0]?.filename, frames[0]] : Object.entries(frames ?? {})[0] ?? [];
+        const r = f?.frame;
+        return r && [r.x, r.y, r.w, r.h].every(Number.isFinite) ? { name: String(name ?? 'frame 0'), ...r } : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function pngsUnder(path) {
+    const s = await stat(path).catch(() => null);
+    if (!s)
+        return [];
+    if (s.isFile())
+        return /\.png$/i.test(path) ? [path] : [];
+    const out = [];
+    for (const e of (await readdir(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.isDirectory())
+            out.push(...await pngsUnder(join(path, e.name)));
+        else if (/\.png$/i.test(e.name))
+            out.push(join(path, e.name));
+    }
+    return out;
+}
+export async function lookSheet(opts, io = console) {
+    const u = ui(io, 'look');
+    const dir = resolve(opts.target ?? '.');
+    const sizes = opts.sizes ? opts.sizes.split(',').map(Number) : SHEET_SIZES;
+    if (!sizes.length || sizes.some((n) => !Number.isInteger(n) || n < 8 || n > 256)) {
+        u.error('--sizes is a list of whole pixel heights from 8 to 256', '--sizes 24,48,96');
+        return EXIT.error;
+    }
+    if (opts.ground && !parseHex(opts.ground)) {
+        u.error(`--ground is a hex colour, not ${opts.ground}`, '--ground #b87a4f');
+        return EXIT.error;
+    }
+    const roots = (opts.sprites ?? join('public', 'assets', 'sprites')).split(',').map((p) => resolve(dir, p.trim()));
+    const files = (await Promise.all(roots.map(pngsUnder))).flat();
+    const sprites = [], skipped = [];
+    const cycles = [];
+    for (const f of files.slice(0, MAX_SPRITES)) {
+        try {
+            const whole = decodePng(await readFile(f)), frame = atlasFrame(f);
+            for (const c of sheetLoops(whole, manifestOf(f)) ?? [])
+                cycles.push({ sheet: relative(dir, f), ...c });
+            const t = trim(frame ? crop(whole, frame.x, frame.y, frame.w, frame.h) : whole);
+            const name = relative(dir, f) + (frame ? `#${frame.name}` : '');
+            if (t)
+                sprites.push({ name, img: t });
+            else
+                skipped.push(`${name} (nothing visible)`);
+        }
+        catch (e) {
+            skipped.push(`${relative(dir, f)} (${e.message})`);
+        }
+    }
+    if (!sprites.length) {
+        if (opts.json)
+            io.log(JSON.stringify({ verdict: 'not_observed', sprites: [], skipped, searched: roots.map((r) => relative(dir, r) || '.') }, null, 2));
+        else
+            u.summary('not_observed', `no PNG sprite under ${roots.map((r) => relative(dir, r) || '.').join(', ')} — pass --sprites dir,file… (nothing measured is never a pass)`);
+        return EXIT.not_observed;
+    }
+    const ground = groundColour(dir, opts.ground);
+    const band = ground?.rgb ?? NEUTRAL;
+    const { img, cells } = composeSheet(sprites, band, sizes);
+    const out = resolve(dir, opts.out ?? join('.funtools', 'look', 'sheet.png'));
+    await mkdir(dirname(out), { recursive: true });
+    await writeFile(out, encodePng(img));
+    const on = ground ? 'ground' : 'neutral';
+    const rows = sprites.map((s) => {
+        const at = cells.filter((c) => c.name === s.name && c.band === on);
+        const weakest = at.reduce((w, c) => ((c.contrast?.delta_e ?? Infinity) < (w.contrast?.delta_e ?? Infinity) ? c : w), at[0]);
+        return {
+            name: s.name, source_px: `${s.img.width}x${s.img.height}`,
+            delta_e: Object.fromEntries(at.map((c) => [c.size, c.contrast?.delta_e ?? null])),
+            weakest: { size: weakest.size, delta_e: weakest.contrast?.delta_e ?? null }, reads: at.every((c) => (c.contrast?.delta_e ?? 0) >= READ_MIN_DELTA_E),
+        };
+    });
+    const loopsFail = cycles.some((c) => c.verdict === 'fail');
+    const verdict = rows.every((r) => r.reads) && !loopsFail ? 'pass' : 'fail';
+    const result = { verdict, min_delta_e: READ_MIN_DELTA_E, sizes, ground: ground ? { hex: `#${band.map((c) => c.toString(16).padStart(2, '0')).join('')}`, from: ground.from } : null, file: out, sprites: rows, cycles, skipped };
+    const joined = cycles.filter((c) => c.seam !== null);
+    if (joined.length) {
+        const bad = joined.filter((c) => c.seam !== 'meets');
+        patchBoard(dir, { seams: { [opts.sprites ? `sheets ${opts.sprites}` : 'sheets']: { value: bad.length, by: 'look --sheet', detail: bad.map((c) => `${c.sheet} ${c.cycle}: ${c.seam === 'pops' ? 'pops at the loop' : 'the last frame repeats the first'}`) } } });
+    }
+    if (opts.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return EXIT[verdict];
+    }
+    u.heading(`look --sheet · ${sprites.length} sprite(s) at ${sizes.join('/')} px · measured on ${ground ? `the ground ${result.ground.hex} (${ground.from})` : 'the neutral band only'}`);
+    for (const r of rows) {
+        const des = Object.entries(r.delta_e).map(([s, d]) => `${s} px ΔE ${d ?? '—'}`).join(' · ');
+        u.item(r.reads ? 'pass' : 'fail', `${basename(r.name)}: ${des}`, r.reads ? undefined : `merges at ${r.weakest.size} px: an outline, a rim, a value step or a bigger play size (skill funpixel-art)`);
+    }
+    for (const c of cycles) {
+        const poses = c.distinct_poses === null ? '' : ` · ${c.distinct_poses}/${c.frames} poses`;
+        const seam = c.seam_delta === null ? '' : ` · seam ${Math.round(c.seam_delta * 100)}% vs step ${Math.round((c.median_delta ?? 0) * 100)}%`;
+        const bad = c.verdict === 'fail' || c.verdict === 'warn';
+        u.item(c.verdict, `${c.sheet} ${c.cycle}${c.loop ? ' (loop)' : ''}${poses}${seam}`, bad ? `${c.why.join('; ')} — redraw the odd frame or cut the repeat (skill funpixel-art, sheets)` : undefined);
+    }
+    if (!ground)
+        u.item('note', 'no ground colour: pass --ground #hex or set assets/style.json roles.ground — the real floor is where pieces vanish');
+    for (const s of skipped)
+        u.item('skip', s);
+    u.line(out);
+    const merged = rows.some((r) => !r.reads);
+    u.summary(verdict, verdict === 'pass' ? `every sprite reads at every size${cycles.length ? `; ${cycles.filter((c) => c.verdict !== 'not_observed').length} of ${cycles.length} cycle(s) measured, none pops or freezes` : ''}`
+        : merged ? `a sprite merges with the ${on} (bar ΔE ${READ_MIN_DELTA_E}) — look at the sheet${loopsFail ? '; and a cycle pops or freezes' : ''}` : 'a cycle pops at its loop or holds one pose — see the cycle lines');
+    return EXIT[verdict];
+}

package/dist/commands/look-theme.js

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { contrastReport, LOOK_FILE, LOOK_REPORT, lenient, mergePatch, parseAssignments, readLook, styleDrift, validate } from "../look/theme.js";
+import { plannedFonts } from "../verify/health.js";
+import { firstFamily, isSystemStack } from "../look/ui-style.js";
+import { ui } from "../ui.js";
+export const THEME_SUBCOMMANDS = ['set', 'patch', 'report'];
+function unplannedFonts(dir, look) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(readFileSync(join(dir, 'funpixel.json'), 'utf8'));
+    }
+    catch { }
+    const planned = new Set(plannedFonts(manifest).map((f) => f.toLowerCase()));
+    return ['font-display', 'font-body'].map((k) => look[k]).filter((v) => typeof v === 'string')
+        .filter((v) => !isSystemStack(v)).map(firstFamily).filter((f) => f && !planned.has(f.toLowerCase()));
+}
+function printPairs(u, pairs) {
+    for (const p of pairs) {
+        if (p.ratio === null) {
+            u.item('note', `${p.pair}: ${p.note}`);
+            continue;
+        }
+        if (p.pass) {
+            u.item('pass', `${p.pair} ${p.ratio}:1 (needs ${p.need}) — ${p.what}`);
+            continue;
+        }
+        const fix = p.ink ? `propose ${p.ink} (${p.ink_ratio}:1): funtools look set ${p.pair.split(' on ')[0]}=${p.ink}` : p.note;
+        u.item('warn', `${p.pair} ${p.ratio}:1, needs ${p.need} — ${p.what}`, fix);
+    }
+}
+export async function lookTheme(opts, io = console) {
+    const u = ui(io, `look ${opts.sub}`);
+    const dir = resolve(opts.dir);
+    const cur = readLook(dir);
+    if (opts.sub === 'report') {
+        if (!cur.exists) {
+            u.item('not_observed', `no ${LOOK_FILE}`, 'the starters write one; `funtools look set bg=#1d2a3a` starts one');
+            u.summary('not_observed', 'no look to report');
+            return EXIT.not_observed;
+        }
+        if (cur.parseError) {
+            u.error(`${LOOK_FILE} does not parse: ${cur.parseError}`, 'the game falls back to the stylesheet for every token');
+            return EXIT.fail;
+        }
+        const { applied, fallbacks } = lenient(cur.look);
+        const pairs = contrastReport(applied);
+        const drift = styleDrift(dir, applied), fonts = unplannedFonts(dir, applied);
+        await record(dir, { file: LOOK_FILE, fallbacks, pairs, drift, unplanned_fonts: fonts });
+        if (opts.json) {
+            io.log(JSON.stringify({ file: LOOK_FILE, tokens: Object.keys(applied).length, fallbacks, pairs, drift, unplanned_fonts: fonts }, null, 2));
+            return fallbacks.length ? EXIT.fail : EXIT.pass;
+        }
+        u.heading(`look · ${LOOK_FILE} · ${Object.keys(applied).length} token(s)`);
+        for (const f of fallbacks)
+            u.item('warn', f, 'the game drops it and logs this line; `funtools look set` refuses it');
+        printPairs(u, pairs);
+        for (const d of drift)
+            u.item('note', `the style file and the look disagree: ${d}`, 'carry the art direction\'s choice into look.json, or the style file after it');
+        for (const f of fonts)
+            u.item('note', `"${f}" is not in funpixel.json metadata.fonts`, 'name it there so verify checks it loads');
+        const low = pairs.filter((p) => p.pass === false).length;
+        u.summary(fallbacks.length ? 'fail' : low ? 'warn' : 'pass', fallbacks.length ? `${fallbacks.length} token(s) the game cannot apply` : low ? `${low} pair(s) under their contrast: inks proposed` : 'every token applies and every pair reads');
+        return fallbacks.length ? EXIT.fail : EXIT.pass;
+    }
+    if (cur.parseError) {
+        u.error(`${LOOK_FILE} does not parse: ${cur.parseError}`, 'fix or delete it, then set again');
+        return EXIT.fail;
+    }
+    let patch;
+    if (opts.sub === 'set') {
+        const { patch: p, bad } = parseAssignments(opts.pairs ?? []);
+        if (bad.length || !Object.keys(p).length) {
+            u.error(bad.length ? `not token=value: ${bad.join(' ')}` : 'nothing to set', 'funtools look set plate-ink=#3a2618 font-display="\'Cinzel\', serif"');
+            return EXIT.error;
+        }
+        patch = p;
+    }
+    else {
+        if (!opts.file) {
+            u.error('patch needs a JSON file', 'funtools look patch my-look.json');
+            return EXIT.error;
+        }
+        try {
+            patch = JSON.parse(await readFile(resolve(opts.file), 'utf8'));
+        }
+        catch (e) {
+            u.error(`cannot read ${opts.file}: ${e.message}`);
+            return EXIT.error;
+        }
+        if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+            u.error(`${opts.file} is not a JSON object`);
+            return EXIT.error;
+        }
+    }
+    const next = mergePatch(cur.look, patch);
+    const problems = validate(next);
+    if (problems.length) {
+        if (opts.json)
+            io.log(JSON.stringify({ written: false, problems }, null, 2));
+        else {
+            u.heading(`look ${opts.sub} · refused: nothing written`);
+            for (const p of problems)
+                u.item('fail', `${p.token}: ${p.what}`, p.suggest.length ? `did you mean ${p.suggest.join(', ')}?` : undefined);
+            u.summary('fail', `${problems.length} problem(s) in the merged look; ${LOOK_FILE} is unchanged`);
+        }
+        return EXIT.fail;
+    }
+    const changed = Object.keys({ ...cur.look, ...next }).filter((k) => JSON.stringify(cur.look[k]) !== JSON.stringify(next[k]));
+    await mkdir(dirname(cur.path), { recursive: true });
+    await writeFile(cur.path, JSON.stringify(next, null, 2) + '\n');
+    const pairs = contrastReport(next), drift = styleDrift(dir, next), fonts = unplannedFonts(dir, next);
+    await record(dir, { file: LOOK_FILE, changed, fallbacks: [], pairs, drift, unplanned_fonts: fonts });
+    if (opts.json) {
+        io.log(JSON.stringify({ written: true, changed, pairs, drift, unplanned_fonts: fonts }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`look ${opts.sub} · ${LOOK_FILE}`);
+    for (const k of changed)
+        u.item('pass', `${k}: ${cur.look[k] === undefined ? '(stylesheet)' : JSON.stringify(cur.look[k])} → ${next[k] === undefined ? '(stylesheet)' : JSON.stringify(next[k])}`);
+    printPairs(u, pairs);
+    for (const d of drift)
+        u.item('note', `the style file and the look disagree: ${d}`);
+    for (const f of fonts)
+        u.item('note', `"${f}" is not in funpixel.json metadata.fonts`, 'name it there so verify checks it loads');
+    const low = pairs.filter((p) => p.pass === false).length;
+    u.summary(low ? 'warn' : 'pass', `written${low ? `; ${low} pair(s) under their contrast, inks proposed above` : '; every pair reads'}`);
+    return EXIT.pass;
+}
+async function record(dir, body) {
+    const path = join(dir, LOOK_REPORT);
+    await mkdir(dirname(path), { recursive: true }).catch(() => { });
+    await writeFile(path, JSON.stringify({ at: new Date().toISOString(), ...body }, null, 2) + '\n').catch(() => { });
+}