@funpixel/tools 0.0.0-stage → 0.1.0

package/dist/gdd/measures.js

@@ -0,0 +1,477 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { field } from "./doc.js";
+export const ELEMENTS_PER_HOUR_WARN = 4;
+export const STEAM_WINDOW_MINUTES = 120;
+export const LENGTH_TOLERANCE = 0.1;
+export const REPORT = 'the studio\'s field report (Don\'t Die §1: "A sourced study of 10 peers")';
+export const REPORT_PEERS = {
+    prey: { name: 'Prey', perHour: '1.4', length: null },
+    scorn: { name: 'Scorn', perHour: '2.2', length: null },
+    superhot: { name: 'Superhot', perHour: '2–3', length: null },
+};
+export const PEERS_LINE = 'the sourced peers put good games at about 1.4–3 new elements an hour of first playthrough (Prey 1.4, Scorn 2.2, Superhot 2–3)';
+export const MEASURE_ORDER = ['elements', 'spine', 'sources', 'peers', 'length', 'steam'];
+export const MEASURE_LABEL = {
+    elements: 'elements per hour', spine: 'the spine', sources: 'sources', peers: 'peers', length: 'length totals', steam: 'Steam two-hour check',
+};
+export const lines = (m) => MEASURE_ORDER.map((k) => m[k].line);
+export const warns = (m) => lines(m).filter((l) => l.state === 'warn');
+const PLACEHOLDER = /<[^<>\n]{2,}>/;
+const STARTER = /\(starter default\)/i;
+const EMPTY = /^\s*(?:|[-–—?]+|n\/?a|none|tbd|todo|unknown)\s*$/i;
+const r1 = (n) => Math.round(n * 10) / 10;
+const r2 = (n) => Math.round(n * 100) / 100;
+const plain = (s) => s.replace(/[*_`]/g, '').trim();
+const cells = (l) => l.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+const isRow = (l) => /^\s*\|.*\|\s*$/.test(l);
+const isRule = (l) => /^\s*\|[\s:|-]+\|\s*$/.test(l);
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+function sectionsOf(text) {
+    const ls = text.replace(/\r/g, '').split('\n');
+    const heads = [];
+    let fence = false;
+    ls.forEach((l, at) => {
+        if (/^\s*```/.test(l))
+            fence = !fence;
+        const m = !fence && /^(#{2,4})\s+(.+?)\s*#*\s*$/.exec(l);
+        if (m)
+            heads.push({ at, level: m[1].length, title: plain(m[2]) });
+    });
+    return heads.map((h, i) => {
+        const end = heads.slice(i + 1).find((n) => n.level <= h.level)?.at ?? ls.length;
+        return { title: h.title, level: h.level, body: ls.slice(h.at + 1, end).join('\n') };
+    });
+}
+const find = (secs, re, level) => secs.find((s) => (level === undefined || s.level === level) && re.test(s.title)) ?? null;
+function tablesOf(body) {
+    const out = [];
+    let block = [];
+    const flush = () => {
+        if (block.length >= 2) {
+            const head = cells(block[0]).map((h) => plain(h).toLowerCase());
+            const filler = (r) => r.length > 1 && r.slice(1).every((c) => !plain(c) || PLACEHOLDER.test(c) || /^<[^<>\n]*>$/.test(c.trim()));
+            const rows = block.slice(1).filter((l) => !isRule(l)).map(cells).filter((r) => plain(r[0] ?? '') && !PLACEHOLDER.test(r[0]) && !filler(r) && !STARTER.test(r.join(' ')) && !/^\W*(totals?|sum)\b/i.test(plain(r[0])));
+            out.push({ head, rows });
+        }
+        block = [];
+    };
+    for (const l of body.split('\n')) {
+        if (isRow(l))
+            block.push(l);
+        else
+            flush();
+    }
+    flush();
+    return out;
+}
+const col = (head, re) => head.findIndex((h) => re.test(h));
+export function clockMinutes(s) {
+    const t = plain(s).replace(/[~≈]/g, '');
+    let m = /(?<![\d:.])(\d+):(\d{2}):(\d{2})(?![\d:])/.exec(t);
+    if (m)
+        return Number(m[1]) * 60 + Number(m[2]) + Number(m[3]) / 60;
+    m = /(?<![\d:.])(\d+):(\d{2})(?![\d:])/.exec(t);
+    if (m)
+        return Number(m[1]) + Number(m[2]) / 60;
+    m = /(\d+(?:\.\d+)?)\s*(?:hours?|hrs?|h)(?![a-z])(?:\s*(?:and\s+)?(\d+)\s*(?:minutes?|mins?|m)?(?![a-z]))?/i.exec(t);
+    if (m)
+        return Number(m[1]) * 60 + (m[2] ? Number(m[2]) : 0);
+    m = /(\d+(?:\.\d+)?)\s*(?:m|mins?|minutes?)\b/i.exec(t);
+    if (m)
+        return Number(m[1]);
+    m = /(\d+(?:\.\d+)?)\s*(?:s|secs?|seconds?)\b/i.exec(t);
+    if (m)
+        return Number(m[1]) / 60;
+    return null;
+}
+export function lengthMinutes(s, bareIsMinutes = false) {
+    const t = plain(s).replace(/[~≈,]/g, '');
+    if (/\b(endless|infinite|forever|no end)\b/i.test(t))
+        return null;
+    const range = /(\d+(?:\.\d+)?)\s*(?:–|-|to)\s*(\d+(?:\.\d+)?)\s*(hours?|hrs?|h\b|minutes?|mins?|min\b|m\b)/i.exec(t);
+    if (range) {
+        const mid = (Number(range[1]) + Number(range[2])) / 2;
+        return /^h/i.test(range[3]) ? mid * 60 : mid;
+    }
+    const one = clockMinutes(t);
+    if (one !== null)
+        return one;
+    const bare = /^(\d+(?:\.\d+)?)$/.exec(t);
+    return bare && bareIsMinutes ? Number(bare[1]) : null;
+}
+const fmt = (min) => {
+    if (min < 1)
+        return `${Math.round(min * 60)} s`;
+    if (min < 60)
+        return `${r1(min)} min`;
+    const h = Math.floor(min / 60), m = Math.round(min - h * 60);
+    return m ? `${h} h ${m} min` : `${h} h`;
+};
+export function statedLength(text) {
+    for (const label of ['Length', 'First playthrough', 'First-time length']) {
+        const v = field(text, label);
+        if (v && !PLACEHOLDER.test(v)) {
+            const m = lengthMinutes(v);
+            if (m !== null)
+                return { minutes: m, text: v, from: `**${label}:**` };
+        }
+    }
+    const own = /^\s*\**play length:?\**:?\s*(.+)$/im.exec(text)?.[1];
+    if (own && !STARTER.test(own) && !/^<[^>]*>?/.test(own.trim())) {
+        const m = lengthMinutes(own);
+        if (m !== null)
+            return { minutes: m, text: own.trim(), from: 'Play length:' };
+    }
+    return null;
+}
+const HOOK_MARK = /\((?:the )?hook\)|\[hook\]/i;
+export function sectionMinutes(text, root) {
+    const dir = root ? join(root, 'design', 'spec', 'places') : null;
+    if (dir && existsSync(dir)) {
+        const files = readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+        const rows = [];
+        for (const f of files) {
+            const j = readJson(join(dir, f));
+            const tm = j?.target_minutes;
+            const v = typeof tm === 'number' ? tm : typeof tm?.first_time === 'number' ? tm.first_time : null;
+            if (j && tm !== undefined)
+                rows.push({ name: String(j.name ?? j.id ?? basename(f, '.json')), minutes: v, hook: j.hook === true });
+        }
+        if (rows.some((r) => r.minutes !== null))
+            return total(rows, 'design/spec/places/*.json target_minutes.first_time');
+    }
+    const secs = sectionsOf(text);
+    const sources = [[/^chapters\b/i, 2, '## Chapters'], [/^places\b/i, 2, '## Places'], [/^stages\b/i, undefined, '### Stages']];
+    for (const [re, level, from] of sources) {
+        const s = find(secs, re, level);
+        if (!s)
+            continue;
+        for (const t of tablesOf(s.body)) {
+            const c = col(t.head, /^(length|minutes?|mins?|time|duration|first[- ]time)\b|\bminutes\b/);
+            if (c < 0)
+                continue;
+            const bare = /min/.test(t.head[c]) || /^length$/.test(t.head[c]);
+            const rows = t.rows.map((r) => ({ name: plain(r[0]), minutes: lengthMinutes(r[c] ?? '', bare), hook: r.some((x) => HOOK_MARK.test(x)) }));
+            if (rows.some((r) => r.minutes !== null))
+                return total(rows, `${from} (${t.head[c]})`);
+        }
+    }
+    return null;
+}
+const total = (rows, from) => ({ from, rows, total: r1(rows.reduce((n, r) => n + (r.minutes ?? 0), 0)), complete: rows.every((r) => r.minutes !== null) });
+function ownerTarget(root) {
+    if (!root)
+        return null;
+    const t = Number(readJson(join(root, 'funpixel.json'))?.target_minutes);
+    return Number.isFinite(t) && t > 0 ? t : null;
+}
+export function readLength(text, root) {
+    const stated = statedLength(text), sections = sectionMinutes(text, root), owner = ownerTarget(root);
+    const ownerSays = owner !== null ? `; the owner's target is ${fmt(owner)} (funpixel.json target_minutes, theirs to move)` : '';
+    const base = { stated, sections, owner };
+    if (!stated && !sections)
+        return { ...base, difference: null, line: { check: 'length', state: 'not_given', says: `not given: no stated length and no section carries minutes${ownerSays}`, next: 'a `Play length:` line (first-time minutes) and a minutes column in ## Chapters or ## Places, or target_minutes.first_time in design/spec/places/*.json' } };
+    if (!sections)
+        return { ...base, difference: null, line: { check: 'length', state: 'not_given', says: `the GDD states ${fmt(stated.minutes)} (${stated.from}); no section carries minutes to sum against it${ownerSays}`, next: 'a minutes column in ## Chapters or ## Places (or the places\' spec files) to sum' } };
+    const missing = sections.rows.filter((r) => r.minutes === null).map((r) => r.name);
+    const sum = `${sections.rows.length - missing.length} part(s) of ${sections.from} add up to ${fmt(sections.total)}${missing.length ? ` (${missing.length} carry no minutes: ${missing.slice(0, 6).join(', ')})` : ''}`;
+    if (!stated)
+        return { ...base, difference: null, line: { check: 'length', state: 'not_given', says: `${sum}; the GDD states no length to set them against${ownerSays}`, next: 'a `Play length:` line (first-time minutes to the ending)' } };
+    const diff = r1(sections.total - stated.minutes);
+    const within = Math.abs(diff) <= Math.max(2, LENGTH_TOLERANCE * stated.minutes);
+    const says = `${sum}, against the stated ${fmt(stated.minutes)} (${stated.from} ${stated.text.slice(0, 60)}): ${diff === 0 ? 'no difference' : `${diff > 0 ? '+' : '−'}${fmt(Math.abs(diff))}`}${ownerSays}`;
+    if (within && !missing.length)
+        return { ...base, difference: diff, line: { check: 'length', state: 'pass', says } };
+    if (missing.length && diff <= 0)
+        return { ...base, difference: diff, line: { check: 'length', state: 'note', says, next: 'give the remaining parts their minutes, then the totals compare' } };
+    return { ...base, difference: diff, line: { check: 'length', state: within ? 'note' : 'warn', says, why: 'one length method: the parts\' first-time minutes summed are the game\'s length, and the stated one should agree with them (Don\'t Die §6: each place was measured differently)', next: diff > 0 ? 'cut or shorten a part, or restate the length (the owner\'s call when the length is theirs)' : 'add or lengthen a part, or restate the length (the owner\'s call when the length is theirs)' } };
+}
+const PLAYER_ROW = /^(the )?(player|hero|you)\b|\bplayer[- ](car|ship|character|craft)\b/i;
+const ELEMENT_TABLES = /^(roster|weapons?|tools?|systems?|mechanics?|instruments?|abilities|powers?|gadgets?|enemies|creatures?)\b/i;
+const usesOf = (s) => {
+    const t = plain(s);
+    if (!t || PLACEHOLDER.test(t))
+        return null;
+    if (/^\d+$/.test(t))
+        return Number(t);
+    if (/^(none|no|-|—|0)$/i.test(t))
+        return 0;
+    return t.split(/\s*[,;·]\s*/).filter(Boolean).length;
+};
+export function readElementList(text, root) {
+    const file = root ? join(root, 'design', 'spec', 'elements.json') : null;
+    const j = file && existsSync(file) ? readJson(file) : null;
+    const list = Array.isArray(j) ? j : Array.isArray(j?.elements) ? j.elements : null;
+    if (list) {
+        return {
+            from: 'design/spec/elements.json',
+            elements: list.filter((e) => e && (e.id || e.name)).map((e) => {
+                const debut = e.debut_place !== undefined ? `${e.debut_place}:${e.debut_beat_t ?? ''}` : null;
+                const uses = Array.isArray(e.uses) ? e.uses.filter((u) => String(u) !== debut).length : null;
+                return { name: String(e.name ?? e.id), kind: String(e.kind ?? 'element').toLowerCase(), uses };
+            }),
+        };
+    }
+    const secs = sectionsOf(text);
+    const own = find(secs, /^(the )?elements\b/i, 2);
+    if (own) {
+        const t = tablesOf(own.body).find((x) => x.rows.length);
+        if (t) {
+            const k = col(t.head, /kind|type|class/), u = col(t.head, /uses?|used|reuse|again/);
+            return { from: '## Elements', elements: t.rows.map((r) => ({ name: plain(r[0]), kind: k >= 0 ? plain(r[k] ?? '').toLowerCase() || 'element' : 'element', uses: u >= 0 ? usesOf(r[u] ?? '') : null })) };
+        }
+    }
+    const content = find(secs, /^content$/i, 2);
+    if (!content)
+        return null;
+    const elements = [];
+    const from = [];
+    for (const s of secsUnder(content.body)) {
+        if (!ELEMENT_TABLES.test(s.title))
+            continue;
+        const t = tablesOf(s.body)[0];
+        if (!t)
+            continue;
+        const k = col(t.head, /^kind$|^type$/), u = col(t.head, /uses?|used|reuse|again/);
+        const rows = t.rows.filter((r) => !PLAYER_ROW.test(plain(r[0])));
+        if (!rows.length)
+            continue;
+        from.push(`### ${s.title}`);
+        for (const r of rows)
+            elements.push({ name: plain(r[0]), kind: k >= 0 ? plain(r[k] ?? '').toLowerCase() || s.title.toLowerCase() : s.title.toLowerCase(), uses: u >= 0 ? usesOf(r[u] ?? '') : null });
+    }
+    return elements.length ? { from: `## Content (${from.join(', ')}; the player's own row left out)`, elements } : null;
+}
+function secsUnder(body) { return sectionsOf(body).filter((s) => s.level === 3); }
+export function readElements(text, root, length) {
+    const list = readElementList(text, root);
+    const kinds = {};
+    for (const e of list?.elements ?? [])
+        kinds[e.kind] = (kinds[e.kind] ?? 0) + 1;
+    const count = list?.elements.length ?? 0;
+    const thin = (list?.elements ?? []).filter((e) => e.uses !== null && e.uses < 2).map((e) => e.name);
+    const s = length.sections, st = length.stated;
+    const hoursFrom = s?.complete && s.total > 0 ? `${s.from}, summed` : st ? `${st.from} ${st.text.slice(0, 40)}` : null;
+    const minutes = s?.complete && s.total > 0 ? s.total : st?.minutes ?? null;
+    const hours = minutes !== null ? r2(minutes / 60) : null;
+    const base = { from: list?.from ?? null, count, kinds, hours, hoursFrom, thin };
+    if (!list)
+        return { ...base, perHour: null, line: { check: 'elements', state: 'not_given', says: 'not given: no elements list (design/spec/elements.json, an ## Elements table, or ### Roster under ## Content)', next: 'an ## Elements table, one row per new mechanic, enemy, tool or system, with its kind, debut and uses after the teach' } };
+    if (!hours)
+        return { ...base, perHour: null, line: { check: 'elements', state: 'not_given', says: `${count} element(s) (${list.from}); no first-playthrough length to set them against`, next: 'a `Play length:` line (first-time minutes to the ending)' } };
+    const perHour = r1(count / hours);
+    const kindsSays = Object.entries(kinds).map(([k, n]) => `${n} ${k}`).join(', ');
+    const says = `${perHour} an hour of first playthrough: ${count} element(s) (${kindsSays}) over ${hours} h (${hoursFrom}; elements from ${list.from})`;
+    const short = minutes < 60 ? '; the peers are games of hours, so under an hour each element weighs more in this rate' : '';
+    const thinNext = thin.length ? `check by hand: ${thin.length} used fewer than twice after the teach (${thin.slice(0, 6).join(', ')}${thin.length > 6 ? ', …' : ''}); a one-time beat by design is fine` : undefined;
+    if (perHour > ELEMENTS_PER_HOUR_WARN) {
+        return { ...base, perHour, line: { check: 'elements', state: 'warn', says: `dense: ${says}`, why: `is each element learned (used again after its teach)? ${PEERS_LINE}; a dense, systemic game can be the choice${short}`, next: thinNext ?? 'deepen what is kept before adding (each element back as teach, then test, then twist), or say in the GDD that the density is the choice' } };
+    }
+    return { ...base, perHour, line: { check: 'elements', state: thin.length ? 'note' : 'pass', says, why: `${PEERS_LINE}${short}`, ...(thinNext ? { next: thinNext } : {}) } };
+}
+const STOP = new Set(['the', 'and', 'you', 'your', 'for', 'with', 'that', 'this', 'its', 'are', 'both', 'from', 'into', 'what', 'who', 'wants', 'want']);
+const stems = (s) => plain(s).toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').split(/\s+/).filter((w) => w.length > 2 && !STOP.has(w)).map((w) => w.replace(/(ing|ed|es|s)$/, ''));
+export function readSpine(text) {
+    const s = find(sectionsOf(text), /^(the )?spine\b/i, 2);
+    const none = { sentence: null, clauses: [], systems: [], none: [], unmatched: [], line: { check: 'spine', state: 'not_given', says: 'not given: no ## The spine (one spine sentence, and a table of system → the clause it serves → genre beat)', next: 'write the spine sentence with its clauses split by ";" and map every system to one clause' } };
+    if (!s)
+        return none;
+    const ls = s.body.split('\n');
+    const labelled = ls.map((l) => /^\s*[-*]?\s*\**(?:the )?spine(?: sentence)?:?\**:?\s*(.+)$/i.exec(l)?.[1]).find(Boolean);
+    const prose = ls.map((l) => l.trim()).find((l) => l && !isRow(l) && !/^[-*]\s/.test(l) && !PLACEHOLDER.test(l) && !/^</.test(l));
+    const raw = (labelled ?? prose ?? '').replace(/^["“]|["”]$/g, '').trim();
+    const sentence = raw && !PLACEHOLDER.test(raw) ? plain(raw).replace(/^["“]|["”]\.?$/g, '') : null;
+    const clauses = sentence ? sentence.split(/\s*;\s*/).map((c) => c.replace(/[.]$/, '').trim()).filter(Boolean) : [];
+    const t = tablesOf(s.body).find((x) => x.rows.length);
+    if (!t && !sentence)
+        return none;
+    if (!t)
+        return { ...none, sentence, clauses, line: { check: 'spine', state: 'not_given', says: `${sentence ? `spine: "${sentence}" (${clauses.length} clause(s))` : 'a ## The spine with no sentence'}; no system table to check`, next: 'a table of system → the clause it serves → genre beat' } };
+    const c = col(t.head, /clause|serves|spine|part/), b = col(t.head, /beat|genre/);
+    const systems = t.rows.map((r) => {
+        const cell = c >= 0 ? plain(r[c] ?? '') : '';
+        let serves = null;
+        const n = /^(?:clause\s*|c)?(\d+)\b/i.exec(cell);
+        if (n && Number(n[1]) >= 1 && Number(n[1]) <= clauses.length)
+            serves = Number(n[1]);
+        else if (cell && !EMPTY.test(cell)) {
+            const w = stems(cell);
+            const lower = cell.toLowerCase().replace(/^["“]|["”]$/g, '');
+            const hit = clauses.findIndex((cl) => cl.toLowerCase().includes(lower) || lower.includes(cl.toLowerCase()) || (w.length > 0 && w.filter((x) => stems(cl).includes(x)).length / w.length >= 0.5));
+            if (hit >= 0)
+                serves = hit + 1;
+        }
+        return { system: plain(r[0]), clause: cell, serves, beat: b >= 0 ? plain(r[b] ?? '') : '' };
+    });
+    const noneRows = systems.filter((x) => !x.clause || EMPTY.test(x.clause)).map((x) => x.system);
+    const unmatched = clauses.length ? systems.filter((x) => x.clause && !EMPTY.test(x.clause) && x.serves === null).map((x) => `${x.system} ("${x.clause}")`) : [];
+    const head = `${systems.length} system(s) against ${sentence ? `"${sentence}" (${clauses.length} clause(s))` : 'no spine sentence'}`;
+    const base = { sentence, clauses, systems, none: noneRows, unmatched };
+    if (noneRows.length)
+        return { ...base, line: { check: 'spine', state: 'warn', says: `${head}: ${noneRows.length} serve none: ${noneRows.join(', ')}${unmatched.length ? `; ${unmatched.length} name words the spine sentence does not have: ${unmatched.slice(0, 5).join(', ')}` : ''}`, why: 'every system was mapped to one clause of the spine, and systems that mapped to none were cut (Don\'t Die §2)', next: 'map each to the clause it serves, or cut it (the owner\'s call when the system was theirs)' } };
+    if (unmatched.length)
+        return { ...base, line: { check: 'spine', state: 'note', says: `${head}: each names a clause; ${unmatched.length} name words the spine sentence does not have: ${unmatched.slice(0, 5).join(', ')}`, next: 'check by hand: quote the clause, or give its number' } };
+    return { ...base, line: { check: 'spine', state: 'pass', says: `${head}: each serves one` } };
+}
+const NOT_CLAIMS = /identity lock|asset script|art budget|first look|linked pages|versions|where the build moved|track|build plan/i;
+const SOURCE_HEAD = /\bsources?\b|^links?$|^citations?$/;
+const SECONDHAND = /approx|from memory|second[- ]?hand|unverified|via |reported by/i;
+const MARKER = /\[(?:source\?|citation needed|needs? (?:a )?source|unsourced)\]/gi;
+export function readSources(text) {
+    const claims = [];
+    const secs = sectionsOf(text);
+    for (const s of secs) {
+        if (NOT_CLAIMS.test(s.title))
+            continue;
+        for (const t of tablesOf(s.body.split(/\n(?=#{2,4}\s)/)[0])) {
+            const c = col(t.head, SOURCE_HEAD);
+            if (c < 0)
+                continue;
+            for (const r of t.rows) {
+                const src = plain(r[c] ?? '');
+                claims.push({ where: s.title, claim: plain(r[0]), source: !src || EMPTY.test(src) || PLACEHOLDER.test(r[c] ?? '') ? null : src });
+            }
+        }
+    }
+    const defs = new Map();
+    for (const m of text.matchAll(/^\s*\[\^([^\]]+)\]:[ \t]*(.*)$/gm))
+        defs.set(m[1], m[2].trim());
+    let current = '';
+    const seen = new Set();
+    for (const l of text.split('\n')) {
+        const h = /^#{1,4}\s+(.+)$/.exec(l);
+        if (h) {
+            current = plain(h[1]);
+            continue;
+        }
+        if (/^\s*\[\^[^\]]+\]:/.test(l))
+            continue;
+        for (const m of l.matchAll(/\[\^([^\]]+)\](?!:)/g)) {
+            if (seen.has(m[1]))
+                continue;
+            seen.add(m[1]);
+            const d = defs.get(m[1]);
+            claims.push({ where: current || 'the head', claim: `${snippet(l)} [^${m[1]}]`, source: d && !EMPTY.test(d) ? d : null });
+        }
+        for (const m of l.matchAll(MARKER))
+            claims.push({ where: current || 'the head', claim: snippet(l), source: null });
+    }
+    const unsourced = claims.filter((c) => c.source === null);
+    const secondhand = claims.filter((c) => c.source !== null && SECONDHAND.test(c.source));
+    if (!claims.length)
+        return { claims: 0, unsourced, secondhand, line: { check: 'sources', state: 'not_given', says: 'not given: the GDD marks no claims (a table with a Source column, a footnote [^n], a [source?] marker)', next: 'give each peer, number and reference a source line' } };
+    const hand = secondhand.length ? `; ${secondhand.length} secondhand (approx, from memory), kept as marked` : '';
+    if (unsourced.length)
+        return { claims: claims.length, unsourced, secondhand, line: { check: 'sources', state: 'warn', says: `${unsourced.length} of ${claims.length} marked claim(s) carry no source line${hand}: ${unsourced.slice(0, 4).map((c) => `${c.where}: ${c.claim}`).join(' · ')}${unsourced.length > 4 ? ` and ${unsourced.length - 4} more (funtools gdd --sources)` : ''}`, why: 'the peers research that decided Don\'t Die\'s length "never invents a number and marks secondhand HowLongToBeat figures" (Don\'t Die §4)', next: 'add the link (or mark it "approx, from memory"), or take the claim out' } };
+    return { claims: claims.length, unsourced, secondhand, line: { check: 'sources', state: secondhand.length ? 'note' : 'pass', says: `${claims.length} marked claim(s), each with a source line${hand}` } };
+}
+const snippet = (l) => {
+    const s = plain(l.replace(/^\s*[-*|]\s*/, '')).replace(/\[\^[^\]]+\]|\[(?:source\?|citation needed|needs? (?:a )?source|unsourced)\]/gi, '').trim();
+    const t = s.replace(/\s+([.,;:])/g, '$1').replace(/\s{2,}/g, ' ');
+    return t.length > 90 ? `${t.slice(0, 87)}…` : t;
+};
+const LINK = /https?:\/\/\S+/;
+export const peerKey = (name) => plain(name).toLowerCase().replace(/\([^)]*\)/g, '').replace(/^the\s+/, '').replace(/[^a-z0-9]+/g, '');
+export function readPeers(text, ours) {
+    const secs = sectionsOf(text).filter((s) => /^(peers?|worth against the genre|comparables?|the shelf)\b/i.test(s.title));
+    const rows = [];
+    const seen = new Set();
+    for (const s of secs) {
+        for (const t of tablesOf(s.body)) {
+            const L = col(t.head, /length|hours|minutes|playtime|hltb|main/), E = col(t.head, /element|per hour|\/\s*h\b|density/), S = col(t.head, SOURCE_HEAD);
+            for (const r of t.rows) {
+                const game = plain(r[0]).replace(/\s+/g, ' ');
+                if (/^(this game|ours|our plan|as planned|the plan)\b|\(ours\)|\(this game\)/i.test(game))
+                    continue;
+                const key = peerKey(game);
+                if (!key || seen.has(key))
+                    continue;
+                seen.add(key);
+                const src = S >= 0 ? r[S] ?? '' : r.join(' ');
+                const linked = LINK.test(src), memory = SECONDHAND.test(src);
+                const own = (i) => {
+                    const v = i >= 0 ? plain(r[i] ?? '') : '';
+                    if (!v || EMPTY.test(v) || PLACEHOLDER.test(r[i] ?? ''))
+                        return { value: null, from: null };
+                    if (linked && !memory)
+                        return { value: v, from: 'gdd' };
+                    return { value: null, from: null, note: memory ? `the GDD's "${v}" is secondhand` : `the GDD's "${v}" has no link` };
+                };
+                const kit = REPORT_PEERS[key];
+                rows.push({ game, length: own(L), perHour: kit ? { value: kit.perHour, from: 'report' } : own(E) });
+            }
+        }
+    }
+    if (!rows.length)
+        return { rows, ours, line: { check: 'peers', state: 'not_given', says: 'not given: the GDD names no peers (## Worth against the genre, or a ## Peers table)', next: 'name 3–5 peers with length and a source each' } };
+    const show = (f) => (f.value ? `${f.value}${f.from === 'report' ? ' (the report)' : ' (the GDD, linked)'}` : 'unknown');
+    const unknown = rows.filter((r) => !r.perHour.value).length;
+    return { rows, ours, line: { check: 'peers', state: 'note', says: `${rows.length} peer(s): ${rows.map((r) => `${r.game} (length ${show(r.length)}, elements/h ${show(r.perHour)})`).join(' · ')}${ours !== null ? ` · this plan ${ours}/h` : ''}`, why: `figures from ${REPORT} where present, else the GDD's own linked figure, else unknown (never guessed)${unknown ? `; ${unknown} without elements per hour` : ''}` } };
+}
+export function steamTarget(text, root) {
+    for (const label of ['Platforms', 'Platform', 'Shelf', 'Stores', 'Store', 'Ships on', 'Target']) {
+        const v = field(text, label);
+        if (v && !PLACEHOLDER.test(v) && /\bsteam\b/i.test(v))
+            return { steam: true, from: `**${label}:**` };
+    }
+    if (root) {
+        const a = readJson(join(root, 'store', 'answers.json'));
+        if (a && typeof a === 'object' && a.steam)
+            return { steam: true, from: 'store/answers.json steam' };
+    }
+    return { steam: false, from: null };
+}
+export function hookTime(text, length) {
+    const f = field(text, 'Hook at');
+    if (f && !PLACEHOLDER.test(f)) {
+        const m = clockMinutes(f);
+        if (m !== null)
+            return { minutes: m, text: f, from: '**Hook at:**' };
+    }
+    const rows = length.sections?.rows ?? [];
+    const at = rows.findIndex((r) => r.hook);
+    if (at >= 0 && rows.slice(0, at).every((r) => r.minutes !== null)) {
+        const m = rows.slice(0, at).reduce((n, r) => n + (r.minutes ?? 0), 0);
+        return { minutes: m, text: `${rows[at].name} begins`, from: `${length.sections.from}, the row marked (hook)` };
+    }
+    const s = find(sectionsOf(text), /^the hook\b/i, 2);
+    for (const t of s ? tablesOf(s.body) : []) {
+        const w = Math.max(0, col(t.head, /^when|^at$|^time/));
+        for (const r of t.rows) {
+            const m = clockMinutes(r[w] ?? '');
+            if (m !== null)
+                return { minutes: m, text: `${plain(r[w])} ${plain(r[w + 1] ?? '')}`.trim(), from: '## The hook, its first timed row' };
+        }
+    }
+    return null;
+}
+export function readSteam(text, root, length) {
+    const target = steamTarget(text, root), hook = hookTime(text, length);
+    const base = { target, hook, window: STEAM_WINDOW_MINUTES };
+    const why = 'Steam refunds anything played under 2 h: a first-time player should reach the hook inside that window (Don\'t Die §5)';
+    if (!hook)
+        return { ...base, line: { check: 'steam', state: 'not_given', says: 'not given: no hook on the GDD\'s clock (a **Hook at:** line, a part marked "(hook)", or a time in ## The hook\'s first row)', next: 'name when a first-time player reaches the hook' } };
+    const at = `the hook lands at ${fmt(hook.minutes)} (${hook.from}: ${hook.text.slice(0, 50)})`;
+    if (!target.steam)
+        return { ...base, line: { check: 'steam', state: 'not_given', says: `${at}; not given: no Steam target named (a **Platforms:** line naming Steam, or store/answers.json steam)` } };
+    if (hook.minutes > STEAM_WINDOW_MINUTES)
+        return { ...base, line: { check: 'steam', state: 'warn', says: `${at}: ${fmt(hook.minutes - STEAM_WINDOW_MINUTES)} past Steam's two-hour refund window (${target.from})`, why, next: 'move the hook earlier on the first playthrough, or frame the first ending as one of several with the hook toward the others before 2 h' } };
+    const whole = length.stated && length.stated.minutes < STEAM_WINDOW_MINUTES ? length.stated.minutes : null;
+    if (whole !== null)
+        return { ...base, line: { check: 'steam', state: 'note', says: `${at}, inside the window; the whole first playthrough (${fmt(whole)}) fits under 2 h too`, why, next: '"the first ending should be framed as one of several, with the hook toward the others landing before 2 h" (Don\'t Die §5)' } };
+    return { ...base, line: { check: 'steam', state: 'pass', says: `${at}, inside Steam's two-hour refund window (${target.from})` } };
+}
+export function readMeasures(text, root = null) {
+    const length = readLength(text, root);
+    const elements = readElements(text, root, length);
+    return {
+        version: 1, advice: true,
+        elements, spine: readSpine(text), sources: readSources(text), peers: readPeers(text, elements.perHour), length, steam: readSteam(text, root, length),
+    };
+}

package/dist/gdd/page.js

@@ -0,0 +1,111 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { designDoc, field, section } from "./doc.js";
+import { readAssetManifest } from "../assets/manifest.js";
+export const FIRST_LOOK = join('design', 'first-look');
+const PICTURE = /\.(png|webp|jpe?g)$/i;
+const SOUND = /\.(mp3|wav|ogg|m4a)$/i;
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const ls = (dir, re) => (existsSync(dir) ? readdirSync(dir).filter((f) => re.test(f)).sort() : []);
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+export function readFirstLook(game) {
+    const dir = join(game, FIRST_LOOK);
+    const pics = ls(dir, PICTURE);
+    const doc = designDoc(game);
+    const briefs = {};
+    const outs = [];
+    let items = [];
+    try {
+        items = readAssetManifest(game);
+    }
+    catch { }
+    for (const it of items) {
+        const out = it.out?.split('\\').join('/') ?? '';
+        if (!out.startsWith('design/'))
+            continue;
+        const words = typeof it.subject === 'string' ? it.subject : typeof it.prompt === 'string' ? it.prompt : '';
+        const rel = out.startsWith('design/first-look/') ? out.slice('design/first-look/'.length) : `../${out.slice('design/'.length)}`;
+        if (words)
+            briefs[rel] = words;
+        outs.push(out);
+    }
+    const lock = readJson(join(game, '.funtools', 'assets.lock.json'));
+    const entries = Object.values(lock?.items ?? {});
+    const mine = entries.filter((e) => typeof e.file === 'string' && (e.file.startsWith('design/first-look/') || outs.includes(e.file)));
+    const target = ['png', 'webp', 'jpg', 'jpeg'].map((x) => `design/target.${x}`).find((p) => existsSync(join(game, p)));
+    const settled = section(doc?.text ?? '', 'First look').split('\n').filter((l) => /^\s*[-*]\s+\S/.test(l)).map((l) => l.replace(/^\s*[-*]\s+/, '').trim());
+    return {
+        title: /^#\s+(.+)$/m.exec(doc?.text ?? '')?.[1].trim() ?? readJson(join(game, 'funpixel.json'))?.name ?? 'First look',
+        pitch: field(doc?.text ?? '', 'Pitch'),
+        refs: pics.filter((f) => /^ref[-_]/i.test(f)),
+        keyArt: pics.filter((f) => /^key-?art/i.test(f)),
+        places: pics.filter((f) => /^place[-_]/i.test(f)),
+        frames: [...(target ? [`../${target.slice('design/'.length)}`] : []), ...pics.filter((f) => /^(frame|target)/i.test(f))],
+        cast: pics.filter((f) => /^(cast|roster|sheet)/i.test(f)),
+        hud: existsSync(join(dir, 'hud.html')) ? 'hud.html' : pics.find((f) => /^hud/i.test(f)) ?? null,
+        sfx: ls(join(dir, 'sfx'), SOUND).map((f) => `sfx/${f}`),
+        music: ls(join(dir, 'music'), SOUND).map((f) => `music/${f}`),
+        briefs,
+        credits: mine.length ? mine.reduce((n, e) => n + (e.credits ?? 0), 0) : null,
+        settled,
+    };
+}
+const nameOf = (f) => f.replace(/^.*\//, '').replace(/\.[a-z0-9]+$/i, '').replace(/^(frame|target|sfx|music)[-_]?/i, '').replace(/[-_]+/g, ' ') || f;
+function figure(f, briefs) {
+    const brief = briefs[f];
+    return `<figure><img loading="lazy" src="${esc(f)}" alt="${esc(brief || nameOf(f))}"><figcaption><b>${esc(nameOf(f))}</b>${brief ? ` · ${esc(brief)}` : ''}</figcaption></figure>`;
+}
+function clip(f, briefs) {
+    return `<div class="clip"><b>${esc(nameOf(f))}</b>${briefs[f] ? `<p>${esc(briefs[f])}</p>` : ''}<audio controls preload="none" src="${esc(f)}"></audio></div>`;
+}
+export function renderFirstLook(l) {
+    const part = (title, body) => (body ? `<section><h2>${title}</h2>${body}</section>` : '');
+    const hud = !l.hud ? '' : l.hud.endsWith('.html')
+        ? `<div class="phone"><iframe src="hud.html" title="Phone HUD mockup" loading="lazy"></iframe></div><p class="note">An HTML mockup at a phone's size, drawn over a target frame.</p>`
+        : figure(l.hud, l.briefs);
+    const missing = [
+        !l.keyArt.length && 'key art', l.frames.length < 4 && `${4 - l.frames.length} of 4 target frames`, !l.cast.length && 'the cast sheet',
+        !l.hud && 'the phone HUD mockup', !l.sfx.length && 'sound cues', !l.music.length && 'music',
+    ].filter(Boolean);
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(l.title)} · first look</title>
+<style>
+:root{--bg:#f4f3ef;--ink:#16161a;--muted:#5d5d66;--line:#dcdad3;--card:#fff}
+@media (prefers-color-scheme:dark){:root{--bg:#111114;--ink:#ecebe6;--muted:#a3a3ad;--line:#2a2a31;--card:#19191e}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 system-ui,sans-serif}
+main{max-width:1100px;margin:0 auto;padding:32px 16px 64px}h1{font-size:clamp(32px,6vw,54px);margin:0 0 6px}
+h2{font-size:20px;margin:40px 0 12px}.pitch{font-size:19px;color:var(--muted);max-width:62ch}.tag{font-size:12px;letter-spacing:.1em;text-transform:uppercase;color:var(--muted)}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,320px),1fr));gap:16px}
+figure{margin:0}img{display:block;width:100%;height:auto;border-radius:10px;border:1px solid var(--line)}figcaption{font-size:14px;color:var(--muted);margin-top:6px}
+.clips{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,240px),1fr));gap:12px}.clip{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px}
+.clip p{margin:4px 0 8px;font-size:14px;color:var(--muted)}audio{width:100%}
+.phone{background:#0b0b0e;border-radius:28px;padding:12px;max-width:900px}.phone iframe{display:block;width:100%;aspect-ratio:852/393;border:0;border-radius:18px;background:#000}
+.note{font-size:14px;color:var(--muted)}ul{padding-left:1.2em}
+</style></head><body><main>
+<span class="tag">First look · generated targets, not engine captures</span>
+<h1>${esc(l.title)}</h1>
+${l.pitch ? `<p class="pitch">${esc(l.pitch)}</p>` : ''}
+${part('Identity lock', l.refs.length ? `<p class="note">Reference sheets: every recurring design is drawn to these.</p><div class="grid">${l.refs.map((f) => figure(f, l.briefs)).join('')}</div>` : '')}
+${part('Key art', l.keyArt.map((f) => figure(f, l.briefs)).join(''))}
+${part('Target frames', l.frames.length ? `<div class="grid">${l.frames.map((f) => figure(f, l.briefs)).join('')}</div>` : '')}
+${part('Places', l.places.length ? `<div class="grid">${l.places.map((f) => figure(f, l.briefs)).join('')}</div>` : '')}
+${part('The cast', l.cast.map((f) => figure(f, l.briefs)).join(''))}
+${part('The HUD on a phone', hud)}
+${part('Sound', l.sfx.length ? `<div class="clips">${l.sfx.map((f) => clip(f, l.briefs)).join('')}</div>` : '')}
+${part('Music', l.music.length ? `<div class="clips">${l.music.map((f) => clip(f, l.briefs)).join('')}</div>` : '')}
+${part('What it settled', l.settled.length ? `<ul>${l.settled.map((s) => `<li>${esc(s)}</li>`).join('')}</ul>` : '')}
+<p class="note">${l.credits === null ? 'Spend: not recorded (made outside funtools assets).' : `Spend recorded by funtools assets: ${l.credits} credits.`}${missing.length ? ` Not in this look yet: ${esc(missing.join(', '))}.` : ''}</p>
+</main></body></html>
+`;
+}
+export function writeFirstLook(game) {
+    const l = readFirstLook(game);
+    writeFileSync(join(game, FIRST_LOOK, 'index.html'), renderFirstLook(l));
+    return l;
+}