@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/assets/pixelart.js

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { lab, parseHex } from "../look/readability.js";
+export const SCALE_RANGE = [1, 32];
+const SAME = 6;
+const ALPHA_SOLID = 248, ALPHA_CLEAR = 8;
+export const PIXEL_LIMITS = { mixedBlocks: 0.02, softAlpha: 0.01, offPalette: 0.01 };
+export function readPixelArt(game) {
+    const p = join(game, 'funpixel.json');
+    if (!existsSync(p))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(p, 'utf8')).pixelArt;
+    }
+    catch {
+        return null;
+    }
+    if (raw === undefined || raw === null || raw === false)
+        return null;
+    const r = raw;
+    const scale = Number(r.scale);
+    if (!Number.isInteger(scale) || scale < SCALE_RANGE[0] || scale > SCALE_RANGE[1])
+        throw new Error(`funpixel.json pixelArt.scale is a whole number of screen pixels per art pixel, ${SCALE_RANGE.join('–')} — e.g. "scale": 4`);
+    const pal = r.palette === undefined ? [] : r.palette;
+    if (!Array.isArray(pal) || pal.some((h) => typeof h !== 'string' || !parseHex(h)) || (pal.length > 0 && (pal.length < 2 || pal.length > 256))) {
+        throw new Error('funpixel.json pixelArt.palette is 2–256 "#rrggbb" colours — or leave it out to snap without one');
+    }
+    return { scale, palette: [...new Set(pal.map((h) => `#${h.replace('#', '').toLowerCase()}`))] };
+}
+function nearestInk(palette) {
+    const inks = palette.map((h) => { const c = parseHex(h); return lab(c[0], c[1], c[2]); });
+    const cache = new Map();
+    return (r, g, b) => {
+        const key = (r << 16) | (g << 8) | b;
+        let best = cache.get(key);
+        if (best !== undefined)
+            return best;
+        const p = lab(r, g, b);
+        let d = Infinity;
+        best = 0;
+        inks.forEach((q, i) => { const e = (p[0] - q[0]) ** 2 + (p[1] - q[1]) ** 2 + (p[2] - q[2]) ** 2; if (e < d) {
+            d = e;
+            best = i;
+        } });
+        cache.set(key, best);
+        return best;
+    };
+}
+const median = (xs) => { const s = xs.sort((a, b) => a - b); return s[s.length >> 1]; };
+export function snapPixels(img, art, size) {
+    const target = size ?? { w: img.width, h: img.height };
+    const nw = Math.max(1, Math.round(target.w / art.scale)), nh = Math.max(1, Math.round(target.h / art.scale));
+    const ink = art.palette.length ? nearestInk(art.palette) : null;
+    const inks = art.palette.map((h) => parseHex(h));
+    const cells = new Uint8Array(nw * nh * 4);
+    for (let cy = 0; cy < nh; cy++) {
+        const y0 = Math.floor((cy * img.height) / nh), y1 = Math.max(y0 + 1, Math.floor(((cy + 1) * img.height) / nh));
+        for (let cx = 0; cx < nw; cx++) {
+            const x0 = Math.floor((cx * img.width) / nw), x1 = Math.max(x0 + 1, Math.floor(((cx + 1) * img.width) / nw));
+            const votes = new Map();
+            const rs = [], gs = [], bs = [];
+            let total = 0;
+            for (let y = y0; y < y1; y++) {
+                for (let x = x0; x < x1; x++) {
+                    const i = (y * img.width + x) * 4;
+                    total++;
+                    if (img.data[i + 3] < 128)
+                        continue;
+                    if (ink) {
+                        const k = ink(img.data[i], img.data[i + 1], img.data[i + 2]);
+                        votes.set(k, (votes.get(k) ?? 0) + 1);
+                    }
+                    else {
+                        rs.push(img.data[i]);
+                        gs.push(img.data[i + 1]);
+                        bs.push(img.data[i + 2]);
+                    }
+                }
+            }
+            const opaque = ink ? [...votes.values()].reduce((s, n) => s + n, 0) : rs.length;
+            if (opaque * 2 < total)
+                continue;
+            const c = ink ? inks[[...votes.entries()].reduce((a, b) => (b[1] > a[1] ? b : a))[0]] : [median(rs), median(gs), median(bs)];
+            cells.set([c[0], c[1], c[2], 255], (cy * nw + cx) * 4);
+        }
+    }
+    const s = art.scale, W = nw * s, H = nh * s;
+    const out = new Uint8Array(W * H * 4);
+    for (let y = 0; y < H; y++)
+        for (let x = 0; x < W; x++)
+            out.set(cells.subarray(((Math.floor(y / s) * nw) + Math.floor(x / s)) * 4, ((Math.floor(y / s) * nw) + Math.floor(x / s)) * 4 + 4), (y * W + x) * 4);
+    return { width: W, height: H, data: out };
+}
+const hex = (r, g, b) => `#${[r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+const round4 = (n) => Math.round(n * 10000) / 10000;
+function gridOffset(img, scale) {
+    const hx = new Array(scale).fill(0), hy = new Array(scale).fill(0);
+    const differs = (i, j) => Math.abs(img.data[i] - img.data[j]) > SAME || Math.abs(img.data[i + 1] - img.data[j + 1]) > SAME
+        || Math.abs(img.data[i + 2] - img.data[j + 2]) > SAME || (img.data[i + 3] >= 128) !== (img.data[j + 3] >= 128);
+    for (let y = 0; y < img.height; y++) {
+        for (let x = 0; x < img.width; x++) {
+            const i = (y * img.width + x) * 4;
+            if (x > 0 && differs(i, i - 4))
+                hx[x % scale]++;
+            if (y > 0 && differs(i, i - img.width * 4))
+                hy[y % scale]++;
+        }
+    }
+    const argmax = (h) => h.reduce((best, v, i) => (v > h[best] ? i : best), 0);
+    return [argmax(hx), argmax(hy)];
+}
+export function measurePixels(img, art) {
+    const { width: W, height: H, data: d } = img;
+    const s = art.scale;
+    let grid;
+    if (s === 1)
+        grid = { verdict: 'not_observed', scale: s, offset: [0, 0], blocks: 0, mixed: 0, share: 0, note: 'scale 1: every picture is on a one-pixel grid' };
+    else {
+        const [ox, oy] = gridOffset(img, s);
+        let blocks = 0, mixed = 0;
+        for (let by = oy; by + s <= H; by += s) {
+            for (let bx = ox; bx + s <= W; bx += s) {
+                const f = (by * W + bx) * 4;
+                let any = false, bad = false;
+                for (let y = by; y < by + s && !bad; y++) {
+                    for (let x = bx; x < bx + s; x++) {
+                        const i = (y * W + x) * 4;
+                        if (d[i + 3] >= ALPHA_CLEAR)
+                            any = true;
+                        if ((d[i + 3] >= 128) !== (d[f + 3] >= 128) || (d[i + 3] >= 128 && (Math.abs(d[i] - d[f]) > SAME || Math.abs(d[i + 1] - d[f + 1]) > SAME || Math.abs(d[i + 2] - d[f + 2]) > SAME))) {
+                            bad = true;
+                            any = true;
+                            break;
+                        }
+                    }
+                }
+                if (!any)
+                    continue;
+                blocks++;
+                if (bad)
+                    mixed++;
+            }
+        }
+        const share = blocks ? mixed / blocks : 0;
+        grid = blocks
+            ? { verdict: share > PIXEL_LIMITS.mixedBlocks ? 'fail' : 'pass', scale: s, offset: [ox, oy], blocks, mixed, share: round4(share) }
+            : { verdict: 'not_observed', scale: s, offset: [ox, oy], blocks: 0, mixed: 0, share: 0, note: `no complete ${s}×${s} block with anything drawn in it` };
+    }
+    let drawn = 0, soft = 0;
+    for (let i = 3; i < d.length; i += 4) {
+        if (d[i] < ALPHA_CLEAR)
+            continue;
+        drawn++;
+        if (d[i] < ALPHA_SOLID)
+            soft++;
+    }
+    const alpha = drawn
+        ? { verdict: soft / drawn > PIXEL_LIMITS.softAlpha ? 'fail' : 'pass', soft, share: round4(soft / drawn) }
+        : { verdict: 'not_observed', soft: 0, share: 0, note: 'nothing drawn' };
+    let palette;
+    if (!art.palette.length)
+        palette = { verdict: 'not_observed', off: 0, share: 0, top: [], note: 'no palette declared (funpixel.json pixelArt.palette)' };
+    else {
+        const inks = art.palette.map((h) => parseHex(h));
+        const known = new Map(), offs = new Map();
+        let opaque = 0, off = 0;
+        for (let i = 0; i < d.length; i += 4) {
+            if (d[i + 3] < 128)
+                continue;
+            opaque++;
+            const key = (d[i] << 16) | (d[i + 1] << 8) | d[i + 2];
+            let ok = known.get(key);
+            if (ok === undefined) {
+                ok = inks.some((c) => Math.abs(c[0] - d[i]) <= SAME && Math.abs(c[1] - d[i + 1]) <= SAME && Math.abs(c[2] - d[i + 2]) <= SAME);
+                known.set(key, ok);
+            }
+            if (!ok) {
+                off++;
+                const h = hex(d[i], d[i + 1], d[i + 2]);
+                offs.set(h, (offs.get(h) ?? 0) + 1);
+            }
+        }
+        const top = [...offs.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3);
+        palette = opaque
+            ? { verdict: off / opaque > PIXEL_LIMITS.offPalette ? 'fail' : 'pass', off, share: round4(off / opaque), top }
+            : { verdict: 'not_observed', off: 0, share: 0, top: [], note: 'no opaque pixel' };
+    }
+    const parts = [grid.verdict, alpha.verdict, palette.verdict];
+    const verdict = parts.includes('fail') ? 'fail' : parts.includes('pass') ? 'pass' : 'not_observed';
+    return { width: W, height: H, verdict, grid, alpha, palette };
+}

package/dist/assets/pixels.js

@@ -0,0 +1,131 @@
+const ALPHA_MIN = 8;
+export function opaqueBox(img, pad = 2) {
+    let x0 = img.width, y0 = img.height, x1 = -1, y1 = -1;
+    for (let y = 0; y < img.height; y++) {
+        for (let x = 0; x < img.width; x++) {
+            if (img.data[(y * img.width + x) * 4 + 3] < ALPHA_MIN)
+                continue;
+            if (x < x0)
+                x0 = x;
+            if (x > x1)
+                x1 = x;
+            if (y < y0)
+                y0 = y;
+            if (y > y1)
+                y1 = y;
+        }
+    }
+    if (x1 < 0)
+        return null;
+    x0 = Math.max(0, x0 - pad);
+    y0 = Math.max(0, y0 - pad);
+    x1 = Math.min(img.width - 1, x1 + pad);
+    y1 = Math.min(img.height - 1, y1 + pad);
+    return { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 };
+}
+export function crop(img, b) {
+    const data = new Uint8Array(b.w * b.h * 4);
+    for (let y = 0; y < b.h; y++)
+        data.set(img.data.subarray(((b.y + y) * img.width + b.x) * 4, ((b.y + y) * img.width + b.x + b.w) * 4), y * b.w * 4);
+    return { width: b.w, height: b.h, data };
+}
+export const hasAlpha = (img) => {
+    for (let i = 3; i < img.data.length; i += 4)
+        if (img.data[i] < 250)
+            return true;
+    return false;
+};
+export function roleSize(w, h, role) {
+    const s = role?.h ? role.h / h : role?.w ? role.w / w : 1;
+    if (s >= 1)
+        return { w, h };
+    return { w: Math.max(1, Math.round(w * s)), h: Math.max(1, Math.round(h * s)) };
+}
+export function shrink(img, w, h) {
+    if (w === img.width && h === img.height)
+        return img;
+    const out = new Uint8Array(w * h * 4);
+    const sx = img.width / w, sy = img.height / h;
+    for (let y = 0; y < h; y++) {
+        const ya = y * sy, yb = ya + sy;
+        for (let x = 0; x < w; x++) {
+            const xa = x * sx, xb = xa + sx;
+            let r = 0, g = 0, b = 0, a = 0, area = 0;
+            for (let py = Math.floor(ya); py < Math.ceil(yb); py++) {
+                const wy = Math.min(yb, py + 1) - Math.max(ya, py);
+                for (let px = Math.floor(xa); px < Math.ceil(xb); px++) {
+                    const wgt = (Math.min(xb, px + 1) - Math.max(xa, px)) * wy;
+                    const i = (py * img.width + px) * 4, al = img.data[i + 3] * wgt;
+                    r += img.data[i] * al;
+                    g += img.data[i + 1] * al;
+                    b += img.data[i + 2] * al;
+                    a += al;
+                    area += wgt;
+                }
+            }
+            const o = (y * w + x) * 4;
+            if (a > 0) {
+                out[o] = Math.round(r / a);
+                out[o + 1] = Math.round(g / a);
+                out[o + 2] = Math.round(b / a);
+            }
+            out[o + 3] = Math.round(a / area);
+        }
+    }
+    return { width: w, height: h, data: out };
+}
+export const DEPTH_SATURATION = { far: 0.65, mid: 0.75, near: 0.85 };
+export function desaturate(img, keep) {
+    const d = new Uint8Array(img.data);
+    for (let i = 0; i < d.length; i += 4) {
+        const l = 0.2126 * d[i] + 0.7152 * d[i + 1] + 0.0722 * d[i + 2];
+        for (let c = 0; c < 3; c++)
+            d[i + c] = Math.round(l + (d[i + c] - l) * keep);
+    }
+    return { ...img, data: d };
+}
+export function meanLuma(img) {
+    let sum = 0, n = 0;
+    for (let i = 0; i < img.data.length; i += 4) {
+        if (img.data[i + 3] < 128)
+            continue;
+        sum += 0.2126 * img.data[i] + 0.7152 * img.data[i + 1] + 0.0722 * img.data[i + 2];
+        n++;
+    }
+    return n ? sum / n : 0;
+}
+export const TINT_RANGE = [0.7, 1.35];
+export const tintTo = (luma, median) => luma > 0 ? Math.round(Math.min(TINT_RANGE[1], Math.max(TINT_RANGE[0], median / luma)) * 100) / 100 : 1;
+const round3 = (n) => Math.round(n * 1000) / 1000;
+export function measuredAnchors(img) {
+    let cx = 0, cy = 0, n = 0, top = -1, bottom = -1;
+    const span = (y) => {
+        let a = -1, b = -1;
+        for (let x = 0; x < img.width; x++)
+            if (img.data[(y * img.width + x) * 4 + 3] >= 128) {
+                if (a < 0)
+                    a = x;
+                b = x;
+            }
+        return a < 0 ? null : (a + b + 1) / 2;
+    };
+    for (let y = 0; y < img.height; y++) {
+        for (let x = 0; x < img.width; x++) {
+            if (img.data[(y * img.width + x) * 4 + 3] < 128)
+                continue;
+            cx += x + 0.5;
+            cy += y + 0.5;
+            n++;
+            if (top < 0)
+                top = y;
+            bottom = y;
+        }
+    }
+    if (!n)
+        return {};
+    return {
+        center: [round3(cx / n / img.width), round3(cy / n / img.height)],
+        feet: [round3(span(bottom) / img.width), round3((bottom + 1) / img.height)],
+        top: [round3(span(top) / img.width), round3(top / img.height)],
+    };
+}

package/dist/assets/plan.js

@@ -0,0 +1,169 @@
+import { join } from 'node:path';
+import { batchItem, composePrompt, defaultReferences, REFERENCE_RULE, inputHash, isPicture, MAX_REFERENCES, pinsFor, refKey } from "./manifest.js";
+import { shaOf, stateOf } from "./lock.js";
+import { castOf, keepLine, readCast } from "../cast/library.js";
+export const REFS_SENT = 'each sheet rides as an input reference (a file a job of yours made is sent as its asset; any other is imported once, free) and its words (`pins`) ride in the prompt; a `sheet` item sends the words only (the sheet tool takes no references)';
+export function toolOf(req) {
+    switch (req.kind) {
+        case 'sprite': return 'generate_sprite';
+        case 'sound': return 'generate_sound';
+        case 'music': return 'generate_music';
+        case 'sheet': return 'generate_spritesheet';
+        case 'model3d': return 'generate_3d_model';
+        case 'image': return req.transparent ? 'generate_sprite' : 'generate_image';
+        default: return 'generate_image';
+    }
+}
+function estimateInputOf(req) {
+    const params = (req.params ?? {});
+    const input = { ...params, prompt: typeof req.prompt === 'string' ? req.prompt : 'x' };
+    if (req.kind === 'texture' || req.kind === 'strip')
+        input.kind = req.kind;
+    if (req.kind === 'strip' && req.transparent)
+        input.transparent = true;
+    for (const k of ['size', 'quality'])
+        if (req[k] !== undefined)
+            input[k] = req[k];
+    if (req.kind === 'sheet' && !input.asset_id && !req.prompt)
+        input.asset_id = '00000000-0000-0000-0000-000000000000';
+    if (req.kind === 'model3d' && !req.prompt && !input.image_asset_id)
+        input.image_asset_id = '00000000-0000-0000-0000-000000000000';
+    return input;
+}
+export const onlyMatches = (only, name) => only.some((o) => (o.endsWith('*') ? name.startsWith(o.slice(0, -1)) : o === name));
+export function planGen(game, items, style, lock, f = {}) {
+    const statuses = [];
+    const all = [];
+    const makers = new Map(items.filter((i) => i.out).map((i) => [refKey(i.out), i.name]));
+    const cast = readCast(game);
+    const use = (r) => {
+        const path = refKey(r), maker = makers.get(path);
+        return { path, sha256: shaOf(join(game, path)), ...(maker ? { item: maker } : {}) };
+    };
+    for (const it of items) {
+        if (it.cast && !cast.has(it.cast))
+            throw new Error(`${it.name}: "cast" names ${it.cast}, which is not in design/cast/ — accept its master first: funtools cast add ${it.cast} --master <png> --pins "…"`);
+        const source = it.from ? lock.items[it.from] : undefined;
+        const fromAsset = source?.verdict === 'accept' ? source.asset_id : undefined;
+        const entry = lock.items[it.name];
+        const member = it.kind === 'parts' || it.kind === 'sound' || it.kind === 'music' ? undefined : castOf(it.name, cast, it.cast);
+        const byDefault = it.references === undefined && isPicture(it.kind) && it.kind !== 'pose' ? defaultReferences(it, items) : null;
+        const madeBefore = !!byDefault?.refs.length && entry?.verdict === 'accept' && !entry.references;
+        let refs = it.references ?? (byDefault && !madeBefore ? byDefault.refs : []);
+        const castRefs = member && isPicture(it.kind) && it.kind !== 'pose' && it.kind !== 'sheet' && !(Array.isArray(it.references) && !it.references.length)
+            && !(entry?.verdict === 'accept' && !entry.references?.some((r) => r.path === member.master));
+        if (castRefs)
+            refs = [...new Set([member.master, ...(member.turnaround ? [member.turnaround] : []), ...refs.map(refKey)])].slice(0, MAX_REFERENCES);
+        const pins = [...(member && isPicture(it.kind) ? [keepLine(member, it.change)] : []), ...pinsFor(it, items, refs)];
+        const castSource = member && !it.from && (it.kind === 'pose' || it.kind === 'sheet' || it.kind === 'model3d') ? use(member.master) : undefined;
+        const partsSheet = it.kind === 'parts' && it.sheet ? use(it.sheet) : undefined;
+        let req;
+        if (it.kind === 'pose') {
+            req = { kind: 'pose', mode: 'pose', prompt: composePrompt(it, null, pins) ?? keepLine(member, it.change), ...(it.size ? { size: it.size } : {}), ...(it.quality ? { quality: it.quality } : {}), ...(fromAsset ? { asset_id: fromAsset } : {}) };
+        }
+        else if (it.kind === 'rig') {
+            req = { kind: 'rig', ...(fromAsset ? { asset_id: fromAsset } : {}), ...(it.clips ? { clips: it.clips } : {}), ...(it.motions ? { motions: it.motions } : {}), ...(it.retarget ? { retarget: it.retarget } : {}) };
+        }
+        else if (it.kind === 'parts') {
+            req = { kind: 'parts', sheet: it.sheet, ...(it.names ? { names: it.names } : {}), ...(it.grid ? { grid: it.grid } : {}) };
+        }
+        else
+            req = batchItem(it, style, fromAsset, pins);
+        const references = it.kind === 'pose' ? [] : refs.map(use);
+        const hashed = { ...req };
+        if (references.length)
+            hashed.references = references.map((r) => r.sha256);
+        const src = castSource ?? partsSheet;
+        if (src)
+            hashed.source = src.sha256;
+        if (it.optimize)
+            hashed.optimize = it.optimize;
+        const hash = inputHash(hashed);
+        const status = stateOf(game, it, hash, entry);
+        statuses.push(status);
+        const take = (entry?.take ?? 0) + (f.regen?.has(it.name) ? 1 : 0);
+        const base = take ? `${it.name}.t${take}` : it.name;
+        const draws = isPicture(it.kind) || it.kind === 'model3d' ? it.draws ?? 1 : 1;
+        const serverNames = Array.from({ length: draws }, (_, k) => (k ? `${base}.d${k + 1}` : base));
+        const steps = stepsOf(it, req);
+        all.push({ item: it, req, hash, status, serverNames, take, tool: steps[0]?.tool ?? 'local', estimateInput: steps[0]?.input ?? {}, steps, references,
+            ...(member ? { cast: member } : {}), ...(src ? { source: src } : {}),
+            ...(byDefault?.refs.length ? { byDefault: { lane: byDefault.lane, refs: byDefault.refs, applied: !madeBefore } } : {}) });
+    }
+    const named = f.only ?? null;
+    const chosen = all.filter((p) => {
+        if (named && !onlyMatches(named, p.item.name))
+            return false;
+        if (f.family && (p.status.family ?? p.item.kind) !== f.family)
+            return false;
+        if (f.regen?.has(p.item.name))
+            return true;
+        if (f.staleOnly)
+            return p.status.state === 'stale';
+        if (['missing', 'stale', 'pending'].includes(p.status.state))
+            return true;
+        return p.status.state === 'rejected' && !!named;
+    });
+    const names = new Set(chosen.map((p) => p.item.name));
+    for (const p of chosen) {
+        const from = p.item.from;
+        if (from && (names.has(from) || lock.items[from]?.verdict !== 'accept'))
+            p.waitsFor = from;
+        const sheet = [...p.references, ...(p.source ? [p.source] : [])].find((r) => r.item && r.item !== p.item.name && (names.has(r.item) || !r.sha256));
+        if (!p.waitsFor && sheet)
+            p.waitsFor = sheet.item;
+    }
+    return { todo: chosen, statuses, all };
+}
+const ZERO = '00000000-0000-0000-0000-000000000000';
+function stepsOf(it, req) {
+    const steps = [];
+    if (it.kind === 'parts')
+        return steps;
+    if (it.kind === 'pose')
+        steps.push({ tool: 'edit_image', input: { asset_id: ZERO, prompt: String(req.prompt ?? 'x'), mode: 'pose', ...(it.quality ? { quality: it.quality } : {}) } });
+    else if (it.kind === 'rig') {
+        steps.push({ tool: 'rig_model', input: { asset_id: ZERO, ...(it.clips ? { clips: it.clips } : {}) } });
+        if (it.motions)
+            steps.push({ tool: 'author_motion', input: { asset_id: ZERO, motions: it.motions } });
+        if (it.retarget)
+            steps.push({ tool: 'retarget_clips', input: { asset_id: ZERO, donor_character: it.retarget.character, ...(it.retarget.clips ? { clips: it.retarget.clips } : {}) } });
+    }
+    else
+        steps.push({ tool: toolOf(req), input: estimateInputOf(req) });
+    if (it.optimize)
+        steps.push({ tool: 'optimize_model', input: { asset_id: ZERO, device: it.optimize.device, ...(it.optimize.budget ? { budget: it.optimize.budget } : {}) } });
+    return steps;
+}
+export function identityNotes(plans) {
+    const notes = [];
+    const refs = plans.filter((p) => /^ref-/i.test(p.item.name) && isPicture(p.item.kind));
+    for (const r of refs)
+        if (!r.item.pins)
+            notes.push(`${r.item.name}: no "pins" — the design in words (hair, outfit, silhouette, colours) travels into every picture that names this sheet, even where the picture itself cannot`);
+    if (refs.length) {
+        for (const p of plans) {
+            if (!/^look-/i.test(p.item.name) || !isPicture(p.item.kind) || p.item.references !== undefined)
+                continue;
+            notes.push(`${p.item.name}: names no reference sheet while ${refs.map((r) => r.item.name).join(', ')} exist — a recurring design drawn without its sheet drifts (add "references": [its ref-* file])`);
+        }
+    }
+    for (const p of plans) {
+        const d = p.byDefault;
+        if (!d)
+            continue;
+        const rule = REFERENCE_RULE.find((r) => r.lane === d.lane);
+        notes.push(d.applied
+            ? `${p.item.name}: drawn to ${d.refs.join(', ')} by default (${d.lane}: ${rule?.takes}) — name "references" to choose, or [] for none`
+            : `${p.item.name}: made before its default sheet${d.refs.length > 1 ? 's' : ''} ${d.refs.join(', ')} (${d.lane}); kept as made — \`assets regen ${p.item.name} --because "draw it to its sheet"\` draws it to ${d.refs.length > 1 ? 'them' : 'it'}`);
+    }
+    const seen = new Set();
+    for (const p of plans)
+        for (const r of p.references) {
+            if (r.sha256 || r.item || seen.has(r.path))
+                continue;
+            seen.add(r.path);
+            notes.push(`${r.path} (named by ${p.item.name}) is not on disk and no item makes it`);
+        }
+    return notes;
+}