ugly-game 0.2.0 → 0.4.0

package/dist/assets/anim.d.ts

@@ -0,0 +1,13 @@
+export interface AnimChannel {
+    jointIndex: number;
+    path: number;
+    times: Float32Array;
+    values: Float32Array;
+}
+export interface AnimClip {
+    name: string;
+    duration: number;
+    channels: AnimChannel[];
+}
+export declare function packAnim(clip: AnimClip): Uint8Array;
+export declare function unpackAnim(b: Uint8Array): AnimClip;

package/dist/assets/anim.js

@@ -0,0 +1,55 @@
+const u16 = (v) => { const a = new Uint8Array(2); new DataView(a.buffer).setUint16(0, v, true); return a; };
+const u32 = (v) => { const a = new Uint8Array(4); new DataView(a.buffer).setUint32(0, v, true); return a; };
+const i16 = (v) => { const a = new Uint8Array(2); new DataView(a.buffer).setInt16(0, v, true); return a; };
+const f32s = (arr) => new Uint8Array(arr.buffer.slice(arr.byteOffset, arr.byteOffset + arr.byteLength));
+const f32 = (v) => f32s(Float32Array.of(v));
+export function packAnim(clip) {
+    const parts = [];
+    const name = new TextEncoder().encode(clip.name);
+    parts.push(u16(name.length), name, f32(clip.duration), u16(clip.channels.length));
+    for (const ch of clip.channels)
+        parts.push(i16(ch.jointIndex), new Uint8Array([ch.path, 0]), u32(ch.times.length), u32(ch.values.length), f32s(ch.times), f32s(ch.values));
+    const total = parts.reduce((s, p) => s + p.length, 0);
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+export function unpackAnim(b) {
+    const dv = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    let o = 0;
+    const nameLen = dv.getUint16(o, true);
+    o += 2;
+    const name = new TextDecoder().decode(b.subarray(o, o + nameLen));
+    o += nameLen;
+    const duration = dv.getFloat32(o, true);
+    o += 4;
+    const channelCount = dv.getUint16(o, true);
+    o += 2;
+    const channels = [];
+    for (let c = 0; c < channelCount; c++) {
+        const jointIndex = dv.getInt16(o, true);
+        o += 2;
+        const path = dv.getUint8(o);
+        o += 2; // path + pad
+        const tc = dv.getUint32(o, true);
+        o += 4;
+        const vc = dv.getUint32(o, true);
+        o += 4;
+        const times = new Float32Array(tc);
+        for (let i = 0; i < tc; i++) {
+            times[i] = dv.getFloat32(o, true);
+            o += 4;
+        }
+        const values = new Float32Array(vc);
+        for (let i = 0; i < vc; i++) {
+            values[i] = dv.getFloat32(o, true);
+            o += 4;
+        }
+        channels.push({ jointIndex, path, times, values });
+    }
+    return { name, duration, channels };
+}

package/dist/assets/animMoat.d.ts

@@ -0,0 +1,36 @@
+import type { SkelData } from './rig';
+import type { AnimClip } from './anim';
+export interface Discontinuity {
+    tick: number;
+    index: number;
+    jump: number;
+    ratio: number;
+}
+export interface ContinuityResult {
+    ticks: number;
+    components: number;
+    violations: Discontinuity[];
+    clean: boolean;
+}
+/** Generic PATTERN-3 detector: over a deterministic per-tick numeric trace, flag any component whose
+ *  SECOND difference (|x[t+1]-2x[t]+x[t-1]|, i.e. acceleration) spikes far above its own median — a
+ *  pop/teleport. Smooth motion, even fast constant-velocity, has ~zero second difference, so this
+ *  distinguishes a real discontinuity from fast-but-smooth animation. Localizes to tick + index. */
+export declare function continuityScan(trace: Float32Array[], factor?: number, floor?: number): ContinuityResult;
+/** The animation IR: the deterministic per-tick bone-matrix palette for a clip sampled over `ticks`. */
+export declare function animationPaletteTrace(skel: Required<SkelData>, clip: AnimClip, ticks: number): Float32Array[];
+export interface AnimDiscontinuity {
+    clipTime: number;
+    joint: number;
+    element: number;
+    ratio: number;
+}
+export interface AnimContinuity {
+    clean: boolean;
+    ticks: number;
+    duration: number;
+    violations: AnimDiscontinuity[];
+}
+/** Scan a clip for animation pops/blinks over its palette IR; each violation is localized to the exact
+ *  clip-time + joint (+ which palette element). `clean` ⇒ the animation is smooth. */
+export declare function scanAnimationContinuity(skel: Required<SkelData>, clip: AnimClip, ticks?: number, factor?: number, floor?: number): AnimContinuity;

package/dist/assets/animMoat.js

@@ -0,0 +1,55 @@
+// Animation IR + continuity oracle (the moat thesis applied to skinning — shared/moat.ts patterns
+// 1 & 2 are oracle-equivalence and perturbation-sweep; this is PATTERN 3: TEMPORAL CONTINUITY). The
+// per-tick bone palette is a deterministic function of (skeleton, clip, time) — the "animation IR".
+// A well-authored clip is SMOOTH, so any tick whose palette jumps far above that joint's own local
+// motion is a pop/blink — localized to an exact clip-time + joint, a reproducible verdict not a
+// screenshot dispute. This is exactly the class of bug the antipodal-quaternion blink was; wiring it
+// here means a reintroduction is caught automatically instead of on the deployed site.
+import { sampleClipToLocals, forwardKinematics, buildPalette } from './pose';
+/** Generic PATTERN-3 detector: over a deterministic per-tick numeric trace, flag any component whose
+ *  SECOND difference (|x[t+1]-2x[t]+x[t-1]|, i.e. acceleration) spikes far above its own median — a
+ *  pop/teleport. Smooth motion, even fast constant-velocity, has ~zero second difference, so this
+ *  distinguishes a real discontinuity from fast-but-smooth animation. Localizes to tick + index. */
+export function continuityScan(trace, factor = 8, floor = 0.02) {
+    const T = trace.length, C = T ? trace[0].length : 0;
+    const violations = [];
+    if (T < 4)
+        return { ticks: T, components: C, violations, clean: true };
+    for (let i = 0; i < C; i++) {
+        const d2 = new Float64Array(T - 2);
+        for (let t = 1; t < T - 1; t++)
+            d2[t - 1] = Math.abs(trace[t + 1][i] - 2 * trace[t][i] + trace[t - 1][i]);
+        const base = Math.max([...d2].sort((a, b) => a - b)[d2.length >> 1], floor);
+        for (let t = 1; t < T - 1; t++) {
+            const a = d2[t - 1];
+            if (a > floor && a > factor * base)
+                violations.push({ tick: t, index: i, jump: a, ratio: a / base });
+        }
+    }
+    return { ticks: T, components: C, violations, clean: violations.length === 0 };
+}
+/** The animation IR: the deterministic per-tick bone-matrix palette for a clip sampled over `ticks`. */
+export function animationPaletteTrace(skel, clip, ticks) {
+    const seed = Float64Array.from(skel.rootWorld);
+    const out = [];
+    for (let t = 0; t < ticks; t++) {
+        const time = ticks > 1 ? (t / (ticks - 1)) * clip.duration : 0;
+        out.push(buildPalette(forwardKinematics(sampleClipToLocals(clip, time, skel.restLocals), skel.parents, seed), skel.inverseBind));
+    }
+    return out;
+}
+/** Scan a clip for animation pops/blinks over its palette IR; each violation is localized to the exact
+ *  clip-time + joint (+ which palette element). `clean` ⇒ the animation is smooth. */
+export function scanAnimationContinuity(skel, clip, ticks = 120, factor = 8, floor = 0.02) {
+    const r = continuityScan(animationPaletteTrace(skel, clip, ticks), factor, floor);
+    const seen = new Set();
+    const violations = [];
+    for (const v of r.violations) { // dedupe to one entry per (tick,joint)
+        const joint = Math.floor(v.index / 16), key = `${v.tick}:${joint}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        violations.push({ clipTime: ticks > 1 ? (v.tick / (ticks - 1)) * clip.duration : 0, joint, element: v.index % 16, ratio: v.ratio });
+    }
+    return { clean: violations.length === 0, ticks, duration: clip.duration, violations };
+}

package/dist/assets/archetype.d.ts

@@ -0,0 +1,20 @@
+import type { JointTRS } from './pose';
+/** A named attachment point on the shared skeleton. A part tagged for this socket's region welds here. */
+export interface Socket {
+    id: string;
+    jointIndex: number;
+    region: string;
+    restLocal: JointTRS;
+    allowedRegions: string[];
+}
+/** A shared skeleton blueprint. `restLocals`/`rootWorld` drive FK; `inverseBind` is the ORIGINAL bind. */
+export interface Archetype {
+    id: string;
+    jointCount: number;
+    parents: Int16Array;
+    inverseBind: Float32Array;
+    restLocals: JointTRS[];
+    rootWorld: number[];
+    sockets: Socket[];
+    clipLibrary: string[];
+}

package/dist/assets/archetype.js

@@ -0,0 +1,8 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ARCHETYPE — a per-body-plan skeleton "blueprint" (PLATFORM, generic). Every part in a kit welds onto
+// THIS shared skeleton at a named socket, so a finite part library × the shared rig × continuous
+// deformation yields infinite rigged variety (the No Man's Sky method). The skeleton is the joint
+// hierarchy (parents), the bind (inverseBind — kept ORIGINAL so deformed bones push the skin out), the
+// rest pose, and the sockets. Archetypes are authored data; the assembler + retarget consume them.
+// ─────────────────────────────────────────────────────────────────────────────
+export {};

package/dist/assets/assemble.d.ts

@@ -0,0 +1,26 @@
+import { type JointTRS } from './pose';
+import type { RawMesh } from './geometry';
+import type { Archetype } from './archetype';
+import { type PartKit } from './partkit';
+import type { Genome } from './genome';
+import { type StyleGuide } from './style';
+export interface RoleRange {
+    first: number;
+    count: number;
+    region: string;
+    role: string;
+}
+export interface AssembledMesh {
+    mesh: RawMesh;
+    jointCount: number;
+    parents: Int16Array;
+    inverseBind: Float32Array;
+    jointsPerVertex: Uint16Array;
+    weightsPerVertex: Float32Array;
+    restLocals: JointTRS[];
+    rootWorld: number[];
+    roles: RoleRange[];
+    bounds: [number, number, number, number, number, number];
+}
+/** Assemble a rigged creature mesh from a genome. Deterministic + style-conformant. */
+export declare function assemble(arch: Archetype, kit: PartKit, genome: Genome, guide: StyleGuide): AssembledMesh;

package/dist/assets/assemble.js

@@ -0,0 +1,92 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ASSEMBLER — the No Man's Sky core (PLATFORM, pure). Welds a genome's chosen parts onto the shared
+// archetype skeleton, applies continuous deformation, style-conforms, and emits ONE rigged mesh. It is
+// a pure function of (archetype, kit, genome, guide) using only +−×÷/sqrt + dmath, so the same genome
+// yields a byte-identical mesh on any engine — cacheable + replayable (the moat). Key trick: proportion
+// deforms the REST pose (bone lengths) while inverseBind stays the ORIGINAL bind, so FK over the
+// deformed rest pushes the skinned mesh out along lengthened bones (and library clips retarget for free).
+// ─────────────────────────────────────────────────────────────────────────────
+import { composeTRS, invert } from './pose';
+import { mul } from '../mat4';
+import { dsin, dcos } from '../dmath';
+import { resolveKit } from './partkit';
+import { resolveRole } from './style';
+function applyPoint(M, x, y, z) {
+    return [M[0] * x + M[4] * y + M[8] * z + M[12], M[1] * x + M[5] * y + M[9] * z + M[13], M[2] * x + M[6] * y + M[10] * z + M[14]];
+}
+/** Assemble a rigged creature mesh from a genome. Deterministic + style-conformant. */
+export function assemble(arch, kit, genome, guide) {
+    const selected = resolveKit(kit, genome.parts);
+    const prop = genome.proportion;
+    // 1) Deform the shared rig's rest translations (bone lengths). Default per-joint scale = [girth,height,
+    //    girth]; limb sockets add limbLength, head sockets add headScale. inverseBind stays ORIGINAL.
+    const sv = arch.restLocals.map(() => [prop.girth, prop.height, prop.girth]);
+    for (const s of arch.sockets) {
+        const j = s.jointIndex;
+        if (j < 0 || j >= sv.length)
+            continue;
+        const f = s.region === 'limb' ? prop.limbLength : s.region === 'head' ? prop.headScale : 1;
+        sv[j] = [sv[j][0] * f, sv[j][1] * f, sv[j][2] * f];
+    }
+    const restLocals = arch.restLocals.map((r, j) => ({
+        t: [r.t[0] * sv[j][0], r.t[1] * sv[j][1], r.t[2] * sv[j][2]],
+        q: [r.q[0], r.q[1], r.q[2], r.q[3]], s: [r.s[0], r.s[1], r.s[2]],
+    }));
+    // 2) Weld each selected part (deterministic socket order) with its per-part deform, concatenating
+    //    positions/indices/joints/weights into one mesh sharing the archetype's parents + inverseBind.
+    const positions = [], indices = [], joints = [], weights = [], roles = [];
+    let minx = Infinity, miny = Infinity, minz = Infinity, maxx = -Infinity, maxy = -Infinity, maxz = -Infinity;
+    const sockets = [...arch.sockets].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    for (const s of sockets) {
+        const part = selected[s.id];
+        if (!part)
+            continue;
+        const d = genome.partDeform[s.id] ?? { scale: [1, 1, 1], stretch: [1, 1, 1], twist: 0 };
+        // socket joint bind position (= translation of the inverse of its inverseBind) → deform pivots here
+        const j = s.jointIndex, ib = new Float64Array(16);
+        for (let i = 0; i < 16; i++)
+            ib[i] = arch.inverseBind[j * 16 + i];
+        const bind = invert(ib);
+        const bx = bind[12], by = bind[13], bz = bind[14];
+        const half = d.twist / 2, qy = [0, dsin(half), 0, dcos(half)];
+        const Tp = composeTRS([bx, by, bz], [0, 0, 0, 1], [1, 1, 1]);
+        const R = composeTRS([0, 0, 0], qy, [1, 1, 1]);
+        const S = composeTRS([0, 0, 0], [0, 0, 0, 1], [d.scale[0] * d.stretch[0], d.scale[1] * d.stretch[1], d.scale[2] * d.stretch[2]]);
+        const Tn = composeTRS([-bx, -by, -bz], [0, 0, 0, 1], [1, 1, 1]);
+        const W = mul(Tp, mul(R, mul(S, Tn)));
+        const base = positions.length / 3, pv = part.mesh.positions.length / 3;
+        for (let v = 0; v < pv; v++) {
+            const [x, y, z] = applyPoint(W, part.mesh.positions[v * 3], part.mesh.positions[v * 3 + 1], part.mesh.positions[v * 3 + 2]);
+            positions.push(x, y, z);
+            if (x < minx)
+                minx = x;
+            if (y < miny)
+                miny = y;
+            if (z < minz)
+                minz = z;
+            if (x > maxx)
+                maxx = x;
+            if (y > maxy)
+                maxy = y;
+            if (z > maxz)
+                maxz = z;
+            let ws = 0;
+            for (let k = 0; k < 4; k++)
+                ws += part.weights[v * 4 + k];
+            for (let k = 0; k < 4; k++) {
+                joints.push(part.joints[v * 4 + k]);
+                weights.push(ws > 0 ? part.weights[v * 4 + k] / ws : (k === 0 ? 1 : 0));
+            }
+        }
+        for (const idx of part.mesh.indices)
+            indices.push(idx + base);
+        roles.push({ first: base, count: pv, region: part.tag.region, role: resolveRole(guide, part.tag.region) });
+    }
+    return {
+        mesh: { positions: new Float32Array(positions), indices: new Uint32Array(indices) },
+        jointCount: arch.jointCount, parents: arch.parents, inverseBind: arch.inverseBind,
+        jointsPerVertex: new Uint16Array(joints), weightsPerVertex: new Float32Array(weights),
+        restLocals, rootWorld: arch.rootWorld, roles,
+        bounds: positions.length ? [minx, miny, minz, maxx, maxy, maxz] : [0, 0, 0, 0, 0, 0],
+    };
+}

package/dist/assets/genome.d.ts

@@ -0,0 +1,33 @@
+import type { Archetype } from './archetype';
+import { type PartKit } from './partkit';
+export interface PartDeform {
+    scale: [number, number, number];
+    stretch: [number, number, number];
+    twist: number;
+}
+export interface GlobalProportion {
+    height: number;
+    girth: number;
+    limbLength: number;
+    headScale: number;
+}
+export interface PaletteChoice {
+    guideId: string;
+    roleRamp: Record<string, number>;
+}
+export interface Genome {
+    archetypeId: string;
+    partKitVersion: number;
+    seed: number;
+    parts: Record<string, string>;
+    partDeform: Record<string, PartDeform>;
+    proportion: GlobalProportion;
+    palette: PaletteChoice;
+}
+/** Sample a full genome from a seed: pick a part per socket, deform it, set global proportion + palette.
+ *  Per-field seed splits keep draws independent (adding a field can't perturb earlier ones). */
+export declare function sampleGenome(arch: Archetype, kit: PartKit, seed: number): Genome;
+/** Stable canonical string (sorted keys, fixed float precision) → the cache/replay identity. */
+export declare function canonicalizeGenome(g: Genome): string;
+/** Content hash including the kit version (a kit change invalidates caches deterministically). */
+export declare function genomeHash(g: Genome): string;

package/dist/assets/genome.js

@@ -0,0 +1,55 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GENOME — the seeded recipe for one procedural creature (PLATFORM, generic). A genome is a small,
+// canonical, JSON-serializable record referencing parts/roles BY ID (never geometry), so the assembler
+// is a pure function of (genome, partKitVersion): content-hashable, cacheable, and replayable — the
+// moat. Infinite variety = discrete part choice × continuous per-part deform × global proportion ×
+// palette. sampleGenome derives every field from the seed via per-field splits so adding a field can't
+// shift earlier draws. See design/content-architecture.md.
+// ─────────────────────────────────────────────────────────────────────────────
+import { fnv1a } from '../stateTree';
+import { partsForSocket } from './partkit';
+/** Deterministic mulberry32 (local copy so the platform module has no game-code dependency). */
+function rng(seed) {
+    let a = seed >>> 0;
+    return () => { a = (a + 0x6d2b79f5) | 0; let t = Math.imul(a ^ (a >>> 15), 1 | a); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+const lerp = (r, lo, hi) => lo + (hi - lo) * r;
+function hashStr(s) { let h = 2166136261 >>> 0; for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+} return h >>> 0; }
+/** Sample a full genome from a seed: pick a part per socket, deform it, set global proportion + palette.
+ *  Per-field seed splits keep draws independent (adding a field can't perturb earlier ones). */
+export function sampleGenome(arch, kit, seed) {
+    const parts = {}, partDeform = {};
+    for (const s of arch.sockets) {
+        const opts = partsForSocket(kit, s.id, s.allowedRegions);
+        const rp = rng(seed ^ Math.imul(hashStr(s.id), 0x9e3779b1) ^ 0x1001);
+        const rd = rng(seed ^ Math.imul(hashStr(s.id), 0x85ebca77) ^ 0x2002);
+        if (opts.length)
+            parts[s.id] = opts[Math.floor(rp() * opts.length) % opts.length].tag.id;
+        partDeform[s.id] = {
+            scale: [lerp(rd(), 0.85, 1.15), lerp(rd(), 0.85, 1.15), lerp(rd(), 0.85, 1.15)],
+            stretch: [lerp(rd(), 0.9, 1.1), lerp(rd(), 0.9, 1.1), lerp(rd(), 0.9, 1.1)],
+            twist: lerp(rd(), -0.3, 0.3),
+        };
+    }
+    const rprop = rng(seed ^ 0x3003);
+    const proportion = { height: lerp(rprop(), 0.8, 1.3), girth: lerp(rprop(), 0.85, 1.2), limbLength: lerp(rprop(), 0.85, 1.2), headScale: lerp(rprop(), 0.85, 1.25) };
+    const rpal = rng(seed ^ 0x4004);
+    const roleRamp = {};
+    for (const s of arch.sockets)
+        roleRamp[s.region] ??= Math.floor(rpal() * 6);
+    return { archetypeId: arch.id, partKitVersion: kit.version, seed, parts, partDeform, proportion, palette: { guideId: '', roleRamp } };
+}
+/** Stable canonical string (sorted keys, fixed float precision) → the cache/replay identity. */
+export function canonicalizeGenome(g) {
+    const fx = (n) => n.toFixed(6);
+    const parts = Object.keys(g.parts).sort().map((k) => `${k}:${g.parts[k]}`).join(',');
+    const def = Object.keys(g.partDeform).sort().map((k) => { const d = g.partDeform[k]; return `${k}:${d.scale.map(fx)}|${d.stretch.map(fx)}|${fx(d.twist)}`; }).join(',');
+    const p = g.proportion, prop = [p.height, p.girth, p.limbLength, p.headScale].map(fx).join(',');
+    const ramp = Object.keys(g.palette.roleRamp).sort().map((k) => `${k}:${g.palette.roleRamp[k]}`).join(',');
+    return `${g.archetypeId}#${g.partKitVersion}#${parts}#${def}#${prop}#${g.palette.guideId}:${ramp}`;
+}
+/** Content hash including the kit version (a kit change invalidates caches deterministically). */
+export function genomeHash(g) { return fnv1a(canonicalizeGenome(g) + '|' + String(g.partKitVersion)); }

package/dist/assets/genomeExplore.d.ts

@@ -0,0 +1,28 @@
+import type { Archetype } from './archetype';
+import type { PartKit } from './partkit';
+import type { StyleGuide } from './style';
+import { type Genome } from './genome';
+import { type AssembledMesh } from './assemble';
+/** The largest VERTICAL gap between an assembled creature's parts (by role vertex-range Y-extents). A
+ *  big gap means a body region has NO geometry — e.g. dropped mesh primitives (a multi-material sub-mesh
+ *  silently skipped) or a missing socket. Structural validity + bind correctness both MISS this; it is
+ *  the mesh-COMPLETENESS check the pipeline lacked (it hid the "floating head / no chest" render bug). */
+export declare function verticalCoverageGap(a: AssembledMesh): number;
+/** How far an archetype's REST pose is from reconstructing its bind (rest palette vs identity). ~0 means
+ *  skinning at rest leaves the mesh undistorted; a large value means parts will render DISPLACED (floating
+ *  heads / gaps) even though the mesh is structurally valid. This is the render-correctness check the
+ *  structural oracle lacked — the debuggability gap that hid the genome rendering bug. */
+export declare function bindReconstructionError(a: Archetype): number;
+export interface GenomeAudit {
+    seed: number;
+    ok: boolean;
+    failures: string[];
+}
+/** Audit a single genome against all three properties. */
+export declare function auditGenome(arch: Archetype, kit: PartKit, guide: StyleGuide, g: Genome): GenomeAudit;
+export interface GenomeSweep {
+    audits: GenomeAudit[];
+    firstBad: number;
+}
+/** Sample + audit a batch of seeds; firstBad is the index of the first invalid genome (−1 if all ok). */
+export declare function sweep(arch: Archetype, kit: PartKit, guide: StyleGuide, seeds: number[]): GenomeSweep;

package/dist/assets/genomeExplore.js

@@ -0,0 +1,100 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GENOME EXPLORER / ORACLE — the moat for procedural creatures (PLATFORM; cf. worldExplore/fpsAiExplore).
+// A headless sweep that asserts, per genome, the three properties that make procedural bulk safe:
+//   • DETERMINISM  — two independent assembles yield the identical mesh (byte-for-byte).
+//   • VALIDITY     — watertight-rigged-animatable: sockets filled, finite positions, indices <
+//                    vertexCount, joints < jointCount, weights sum 1, roles cover every vertex.
+//   • CONFORMANCE  — every assigned role exists in the StyleGuide (cohesion guaranteed).
+// It localizes the FIRST offending genome, so a broken part (e.g. an out-of-range joint) is caught.
+// ─────────────────────────────────────────────────────────────────────────────
+import { sampleGenome } from './genome';
+import { assemble } from './assemble';
+import { composeTRS, forwardKinematics, buildPalette } from './pose';
+function toMat(arr) { const m = new Float64Array(16); for (let i = 0; i < 16; i++)
+    m[i] = arr[i] ?? 0; return m; }
+/** The largest VERTICAL gap between an assembled creature's parts (by role vertex-range Y-extents). A
+ *  big gap means a body region has NO geometry — e.g. dropped mesh primitives (a multi-material sub-mesh
+ *  silently skipped) or a missing socket. Structural validity + bind correctness both MISS this; it is
+ *  the mesh-COMPLETENESS check the pipeline lacked (it hid the "floating head / no chest" render bug). */
+export function verticalCoverageGap(a) {
+    const pos = a.mesh.positions;
+    const ranges = a.roles.map((r) => { let lo = Infinity, hi = -Infinity; for (let v = r.first; v < r.first + r.count; v++) {
+        const y = pos[v * 3 + 1];
+        if (y < lo)
+            lo = y;
+        if (y > hi)
+            hi = y;
+    } return [lo, hi]; }).filter((r) => r[0] <= r[1]).sort((p, q) => p[0] - q[0]);
+    if (ranges.length < 2)
+        return 0;
+    let cover = ranges[0][1], maxGap = 0;
+    for (let i = 1; i < ranges.length; i++) {
+        const g = ranges[i][0] - cover;
+        if (g > maxGap)
+            maxGap = g;
+        if (ranges[i][1] > cover)
+            cover = ranges[i][1];
+    }
+    return maxGap;
+}
+/** How far an archetype's REST pose is from reconstructing its bind (rest palette vs identity). ~0 means
+ *  skinning at rest leaves the mesh undistorted; a large value means parts will render DISPLACED (floating
+ *  heads / gaps) even though the mesh is structurally valid. This is the render-correctness check the
+ *  structural oracle lacked — the debuggability gap that hid the genome rendering bug. */
+export function bindReconstructionError(a) {
+    const worlds = forwardKinematics(a.restLocals.map((r) => composeTRS(r.t, r.q, r.s)), a.parents, toMat(a.rootWorld));
+    const pal = buildPalette(worlds, a.inverseBind);
+    let d = 0;
+    for (let j = 0; j < a.jointCount; j++)
+        for (let i = 0; i < 16; i++) {
+            const id = i === 0 || i === 5 || i === 10 || i === 15 ? 1 : 0;
+            d = Math.max(d, Math.abs(pal[j * 16 + i] - id));
+        }
+    return d;
+}
+/** Audit a single genome against all three properties. */
+export function auditGenome(arch, kit, guide, g) {
+    const failures = [];
+    try {
+        for (const s of arch.sockets)
+            if (g.parts[s.id] === undefined)
+                failures.push(`socket ${s.id} unfilled`);
+        const a = assemble(arch, kit, g, guide);
+        const vc = a.mesh.positions.length / 3;
+        if (![...a.mesh.positions].every(Number.isFinite))
+            failures.push('non-finite positions');
+        if ([...a.mesh.indices].some((i) => i >= vc))
+            failures.push('index >= vertexCount');
+        if ([...a.jointsPerVertex].some((j) => j >= a.jointCount))
+            failures.push('joint index out of range');
+        let wbad = false;
+        for (let v = 0; v < vc && !wbad; v++) {
+            let s = 0;
+            for (let k = 0; k < 4; k++)
+                s += a.weightsPerVertex[v * 4 + k];
+            if (Math.abs(s - 1) > 1e-4)
+                wbad = true;
+        }
+        if (wbad)
+            failures.push('skin weights do not sum to 1');
+        if (a.roles.reduce((t, r) => t + r.count, 0) !== vc)
+            failures.push('roles do not cover all vertices');
+        if (a.roles.some((r) => guide.roles[r.role] === undefined))
+            failures.push('assigned role not in StyleGuide');
+        const gap = verticalCoverageGap(a), height = a.bounds[4] - a.bounds[1];
+        if (height > 0 && gap > 0.12 * height)
+            failures.push(`vertical geometry gap ${gap.toFixed(2)} of ${height.toFixed(2)} tall — a body region has no mesh (dropped primitive / missing part?)`);
+        const b = assemble(arch, kit, g, guide);
+        if (JSON.stringify([...a.mesh.positions]) !== JSON.stringify([...b.mesh.positions]))
+            failures.push('non-deterministic assemble');
+    }
+    catch (e) {
+        failures.push('assemble threw: ' + e.message);
+    }
+    return { seed: g.seed, ok: failures.length === 0, failures };
+}
+/** Sample + audit a batch of seeds; firstBad is the index of the first invalid genome (−1 if all ok). */
+export function sweep(arch, kit, guide, seeds) {
+    const audits = seeds.map((sd) => auditGenome(arch, kit, guide, sampleGenome(arch, kit, sd)));
+    return { audits, firstBad: audits.findIndex((a) => !a.ok) };
+}

package/dist/assets/geometry.d.ts

@@ -0,0 +1,23 @@
+export interface RawMesh {
+    positions: Float32Array;
+    indices: Uint32Array;
+}
+export declare function compactMesh(positions: Float32Array, indices: Uint32Array, uvs?: Float32Array): {
+    positions: Float32Array;
+    indices: Uint32Array;
+    uvs?: Float32Array;
+};
+export declare function encodeGeometry(m: RawMesh): Promise<{
+    vtx: Uint8Array;
+    idx: Uint8Array;
+    vertexCount: number;
+    indexCount: number;
+}>;
+export declare function decodeGeometry(enc: {
+    vtx: Uint8Array;
+    idx: Uint8Array;
+    vertexCount: number;
+    indexCount: number;
+}): Promise<RawMesh>;
+export declare function encodeUV(uvs: Float32Array): Promise<Uint8Array>;
+export declare function decodeUV(bytes: Uint8Array, vertexCount: number): Promise<Float32Array>;