@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/character/bodyGeometryGuard.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Refuse to conform/package a character add-on whose garment geometry
+ * includes leftover base-body / underwear surfaces — the defect found live
+ * on "Kombes Man" (`d3823cdf-dfac-4a81-a768-6817089d5144`) and "Female
+ * Sweater Top" (`48d7871c-0a95-496f-b50b-9c87b2c64775`): an untextured grey
+ * torso/bra shape baked into the garment's own GLB, visible under the actual
+ * (textured) garment surface. Confirmed in two independent renderers (the
+ * backend's `final-mesh-textured` CPU rasterizer AND the WebGPU studio
+ * capture path) — a real defect in the mesh DATA, not a render bug. See
+ * `run/open-alpha-qa/customizer-followups/thumbnails/scan2/SUMMARY.md` in the
+ * workspace root for the original evidence.
+ *
+ * ── ROOT CAUSE ─────────────────────────────────────────────────────────────
+ * Both items were almost certainly authored in Unreal with a base body /
+ * underwear layer left visible under the garment for authoring convenience,
+ * and the extraction/conform pipeline never stripped it before packaging the
+ * add-on GLB. An add-on's web GLB must contain ONLY the garment surface: it
+ * renders on top of the platform's own real host body at runtime, so a copy
+ * of that body baked into the add-on is never correct, no matter how it got
+ * there.
+ *
+ * ── WHY ISLANDS ARE GROUPED BY SHARED EDGE, NOT SHARED VERTEX ───────────────
+ * The first version of this file grouped triangles into "islands" by shared
+ * VERTEX INDEX. That is too coarse: on the real Kombes Man overalls
+ * primitive, a decimated LOD's simplifier had welded a handful of isolated
+ * vertices between the (real, textured) overalls fabric and the (leftover,
+ * untextured) duplicate leg geometry tucked inside it — an incidental point
+ * of contact, not a shared surface — and vertex-based grouping fused them
+ * into ONE island. Removing that island deleted real garment triangles along
+ * with the leftover ones (confirmed by re-rendering the "fixed" GLB and
+ * finding holes torn in the pant legs that were never there in the source).
+ *
+ * A second attempt went to the opposite extreme — classifying and removing
+ * every triangle independently, from only its own 3 UV corners — and
+ * OVER-removed instead: sampling only 3 texels is noisy enough (seam/padding
+ * bleed) that thousands of genuinely textured pant-leg triangles individually
+ * misread as "mostly untextured".
+ *
+ * Grouping by shared EDGE (both vertices of a triangle side, not just one)
+ * is the fix that keeps both properties: two triangles that are part of the
+ * same authored surface almost always share a full edge, so real garment
+ * geometry stays one connected island; two triangles from DIFFERENT authored
+ * surfaces that happen to have a single decimation-welded vertex in common do
+ * NOT share an edge, so they are never merged. Classifying and stripping at
+ * this island granularity gets a large, statistically stable sample of
+ * texture reads per decision (tens to hundreds, not three) while never
+ * bridging into real garment geometry. Verified against the real Kombes Man
+ * regression: this produces a stripped GLB with the pant legs fully intact
+ * and only the actual leftover-body islands removed (see
+ * `bodyGeometryGuard.spec.ts`'s fixture-backed regression tests).
+ *
+ * ── WHY "SAME MATERIAL, DIFFERENT ISLAND" AND NOT A NAME CHECK ──────────────
+ * Both live regressions disproved the obvious heuristic. Kombes Man's
+ * body-vs-garment islands share ONE material name
+ * (`MI_M_KombesMan_skinning1`) and Female Sweater Top's grey bra shares its
+ * single primitive with the pink sweater fabric (many disconnected islands,
+ * one draw call) — so neither "does the mesh/material name contain 'body'"
+ * nor "which primitive is this" separates them. What DOES separate them,
+ * confirmed by isolating and rendering flagged islands from both real items:
+ *
+ *   1. The island's DOMINANT skin region (by the SAME dominant-joint
+ *      classification `bakeBodyRegions.ts` bakes onto a canonical base body)
+ *      is a region this add-on's OWN slot type is already platform-granted to
+ *      HIDE (`bodyRegionHide.ts`'s `DEFAULT_HIDE_REGIONS_BY_SLOT_TYPE`) — i.e.
+ *      the island sits exactly where the base body's own skin already is, on
+ *      a slot that exists specifically to cover that skin.
+ *   2. The island's own baked base-color texture, sampled at its own UVs
+ *      across many triangles, is overwhelmingly flat/untextured (low
+ *      saturation, mid value — the `graycheck.py` heuristic the original
+ *      evidence scan used) OR fully transparent (never properly unwrapped at
+ *      all) rather than real garment texture.
+ *
+ * A real garment surface skinned to, say, the torso joint (a snug crop top)
+ * is expected and fine; a real garment island is NOT expected to be both
+ * region-duplicate AND textureless at the same time — that combination is
+ * the signature of body/underwear geometry nobody meant to ship. Requiring
+ * BOTH signals together is what keeps this from flagging legitimate
+ * dark/plain/grey-dyed garments (which are textured, just not colourful) or
+ * legitimate underwear-slot items (whose own visible surface is the point,
+ * not a duplicate of the host's hidden skin).
+ *
+ * ── MEASURED PRECISION (READ BEFORE TRUSTING THIS AS AN ORACLE) ──────────────
+ * This check was tuned against the REAL catalogue, not a synthetic fixture:
+ * every one of the 76 live published add-ons was downloaded and scanned, and
+ * every flag it produced was then rendered and inspected by eye.
+ *
+ *   signal                                    flagged  true   false
+ *   region + untextured island (first cut)        19      2      17
+ *   + item-level colored-fraction gate            10      2       8
+ *   + minTotalFlaggedTriangles = 1000 (SHIPPED)    3      2       1
+ *
+ * The one residual false positive is a sneaker whose sole bed and inner
+ * lining read as one large untextured surface on `body_foot_*` (~1800
+ * triangles) — structurally indistinguishable from the real defect by ANY
+ * texture- or region-based signal, because both are "a large untextured
+ * surface where the body already is". Several stronger-sounding ideas were
+ * tried AND REJECTED on evidence, not intuition: distance-to-host-body-surface
+ * (a body copy is 13-30mm off the host after conform, and a real garment shell
+ * is 20-34mm — no separation); UV-footprint area; material alphaMode;
+ * primitive-level transparency. Each is documented at its rejection site.
+ *
+ * That measured residual is why this ships as a REFUSAL WITH A DOCUMENTED
+ * OVERRIDE (`assertNoLeftoverBodyGeometryWithOverride`) rather than an
+ * unconditional hard fail: a false positive blocks one creator's publish with
+ * an itemized, actionable message they can clear, where a false negative ships
+ * a visible body-shaped defect to every existing owner. The pre-fix
+ * catalogue proved which of those failures actually happens.
+ *
+ * A name-pattern check is included too (`skin`/`torso` as a WHOLE word in a
+ * mesh/node/material name) as a secondary, independent trip line, with a
+ * looser texture bar — cheap, and it costs nothing to keep even though it
+ * caught neither of the two real regressions here (their mesh/material names
+ * carry no such marker; see `bodyGeometryGuard.spec.ts`'s regression
+ * fixtures).
+ */
+import type { Document, Material, Primitive } from '@gltf-transform/core';
+import { type HelixBodyRegion } from './bodyRegionHide';
+export interface BodyGeometryFinding {
+    nodeName: string;
+    meshIndex: number;
+    primIndex: number;
+    islandIndex: number;
+    triangleCount: number;
+    dominantRegion: HelixBodyRegion | null;
+    /** Fraction (0-1) of attempted texture samples across this island reading either flat/gray or fully transparent — i.e. no real authored pixel content. */
+    untexturedFraction: number;
+    /** How many samples that fraction is actually computed from. A low count means low confidence — see `minSamplesAttempted`. */
+    samplesAttempted: number;
+    matchedNamePattern: string | null;
+    reason: 'region-and-texture' | 'name-pattern';
+}
+export interface DetectLeftoverBodyGeometryOptions {
+    /** The add-on's own declared slot type, e.g. `character.top@1` — determines which regions it is already platform-granted to hide. */
+    slotType: string;
+    /** An island smaller than this many triangles is skipped (buttons, zippers, cuff bands, seam trims). Default 24. */
+    minTriangles?: number;
+    /** Minimum untextured-sample fraction for the region+texture signal. Default 0.85. */
+    untexturedFractionThreshold?: number;
+    /** Minimum untextured-sample fraction for the name-pattern signal (looser — the name already narrows it). Default 0.5. */
+    namePatternUntexturedFractionThreshold?: number;
+    /** Minimum share of an island's CLASSIFIED (non-unclassified) vertex votes a single region needs to count as "dominant". Default 0.5. */
+    dominantRegionShareThreshold?: number;
+    /** Cap on texture samples taken per island (perf bound on dense meshes). Default 300. */
+    maxSamplesPerIsland?: number;
+    /** An island needs at least this many attempted texture samples before its `untexturedFraction` is trusted. Default 24. */
+    minSamplesAttempted?: number;
+    /**
+     * The ITEM must have at least this fraction of its own sampled surface
+     * reading as genuinely authored texture (`colored`) before ANY island is
+     * reported. Default 0.05.
+     *
+     * ── WHY THIS GATE EXISTS (MEASURED, NOT THEORISED) ──────────────────────────
+     * Leftover body geometry is DEFINED by sitting under a real garment — it is
+     * the duplicate that the garment covers. A garment that has essentially no
+     * authored texture anywhere is just a plain/monochrome garment, and its
+     * flat-grey surface IS the garment rather than a body copy beneath it. Without
+     * this gate the region+texture signal fires on every plain grey item in the
+     * catalogue — measured against all 76 live add-ons, it flagged 19, of which a
+     * visual audit of every one showed 18 were ordinary plain-grey or dark
+     * garments (an all-grey tee, an all-grey knit sneaker, a black boot, a brown
+     * hair card, a Lakers-coloured short's dark trim). THIS GATE IS THE SINGLE
+     * MEASUREMENT THAT SEPARATES THEM: it clears 14 of those 18 outright.
+     *
+     * See the class doc's "MEASURED PRECISION" section for the residual
+     * false-positive rate this gate leaves and why the check ships as a
+     * refusable-with-override trip line rather than a silent, always-fatal gate.
+     */
+    itemColoredFractionFloor?: number;
+    /**
+     * The item's flagged islands must total at least this many triangles before
+     * anything is reported. Default 1000.
+     *
+     * ── WHY (MEASURED) ──────────────────────────────────────────────────────────
+     * Leftover BODY geometry is a body-sized surface; a garment's own dark trim,
+     * inner lining, sole bed or padding is not. Measured against all 76 live
+     * add-ons after the item-level colored gate above, the eight surviving
+     * false positives (a boot's lining, a plaid skirt's underskirt, a shirt's
+     * dark trim, a sneaker's bed, …) each totalled 65–543 flagged triangles,
+     * while the two real regressions totalled 2158 and 1897. 1000 sits in the
+     * empty gap between them and clears seven of those eight.
+     *
+     * The one residual false positive this does NOT clear (a sneaker whose bed
+     * and lining read as one large untextured surface, ~1800 triangles) is
+     * documented in the class doc's "MEASURED PRECISION" section and is the
+     * reason `assertNoLeftoverBodyGeometry` ships with an explicit caller
+     * override rather than being unconditionally fatal.
+     */
+    minTotalFlaggedTriangles?: number;
+}
+export interface TriangleIsland {
+    /** Starting index (into the primitive's index accessor) of each triangle belonging to this island. */
+    triangleStarts: number[];
+    vertices: Set<number>;
+}
+/**
+ * Group a primitive's triangles into connected surfaces by SHARED EDGE (both
+ * vertices of a triangle side), not shared vertex — see file header for why
+ * this is the correct granularity: it keeps one authored surface as one
+ * island while never bridging two surfaces that merely happen to touch at a
+ * single decimation-welded point. Exported for reuse by the strip tool.
+ */
+export declare function findTriangleIslands(prim: Primitive): TriangleIsland[];
+export interface DecodedTexture {
+    width: number;
+    height: number;
+    /** RGBA, row-major, top-first (glTF UV origin) — same convention as the backend's `mesh-rasterizer.mjs`. */
+    data: Buffer;
+}
+export declare function decodeMaterialBaseColor(material: Material): Promise<DecodedTexture | null>;
+/**
+ * Scan every skinned mesh primitive in `document` for triangle islands
+ * (edge-adjacency — see file header) that look like leftover
+ * base-body/underwear geometry. Returns every finding; callers decide
+ * whether to throw (`assertNoLeftoverBodyGeometry`) or just report.
+ */
+export declare function detectLeftoverBodyGeometry(document: Document, options: DetectLeftoverBodyGeometryOptions): Promise<BodyGeometryFinding[]>;
+/** Human-readable summary for an error message / CLI report — one line per finding. */
+export declare function describeFindings(findings: readonly BodyGeometryFinding[]): string;
+/**
+ * Throws with a full, itemized report if `document` contains anything that
+ * looks like leftover base-body/underwear geometry. This is the gate
+ * `executeCharacterAddon` calls right after `importCharacter` produces the
+ * add-on's final GLB — the add-on is not a valid deliverable until this
+ * passes, exactly like `assertLooksLikeGlb`/`inspectBaseAvatarGlb` gate the
+ * OTHER ways a character artifact can be malformed.
+ */
+export declare function assertNoLeftoverBodyGeometry(document: Document, options: DetectLeftoverBodyGeometryOptions): Promise<void>;
+export interface AssertNoLeftoverBodyGeometryOptions extends DetectLeftoverBodyGeometryOptions {
+    /**
+     * Package the add-on even when the trip line fires. Use ONLY after a human
+     * has looked at the item and confirmed the flagged surface is a legitimate
+     * garment panel rather than a duplicate of the host body — see the class
+     * doc's "MEASURED PRECISION" section for the residual false-positive class
+     * this exists for.
+     */
+    allowFalsePositive?: boolean;
+}
+/**
+ * Same as `assertNoLeftoverBodyGeometry`, but records and swallows a
+ * confirmed false positive instead of refusing — the escape hatch the bridge
+ * exposes so a creator is never permanently blocked by the trip line.
+ */
+export declare function assertNoLeftoverBodyGeometryWithOverride(document: Document, options: AssertNoLeftoverBodyGeometryOptions): Promise<BodyGeometryFinding[]>;

package/dist/character/bodyGeometryGuard.js

@@ -0,0 +1,417 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findTriangleIslands = findTriangleIslands;
+exports.decodeMaterialBaseColor = decodeMaterialBaseColor;
+exports.detectLeftoverBodyGeometry = detectLeftoverBodyGeometry;
+exports.describeFindings = describeFindings;
+exports.assertNoLeftoverBodyGeometry = assertNoLeftoverBodyGeometry;
+exports.assertNoLeftoverBodyGeometryWithOverride = assertNoLeftoverBodyGeometryWithOverride;
+const sharp_1 = __importDefault(require("sharp"));
+const ktx2Decode_1 = require("./ktx2Decode");
+const bodyRegionHide_1 = require("./bodyRegionHide");
+const bakeBodyRegions_1 = require("./bakeBodyRegions");
+const DEFAULT_MIN_TRIANGLES = 24;
+const DEFAULT_UNTEXTURED_FRACTION_THRESHOLD = 0.85;
+const DEFAULT_NAME_PATTERN_UNTEXTURED_FRACTION_THRESHOLD = 0.5;
+const DEFAULT_DOMINANT_REGION_SHARE_THRESHOLD = 0.5;
+const DEFAULT_MAX_SAMPLES_PER_ISLAND = 300;
+const DEFAULT_MIN_SAMPLES_ATTEMPTED = 24;
+const DEFAULT_ITEM_COLORED_FRACTION_FLOOR = 0.05;
+const DEFAULT_MIN_TOTAL_FLAGGED_TRIANGLES = 1000;
+/**
+ * Whole-TOKEN match only, so "Bralette"/"Embrace"/"Torsolette" never trip this — see file header.
+ * Deliberately NOT a `\b` regex: `\b` treats underscore as a word character, so it never creates a
+ * boundary in the underscore-delimited names this pipeline actually sees (Unreal/DCC exports name
+ * things like `SM_CharacterBody_Torso` or `MI_M_KombesMan_skin1`) — `\btorso\b` would silently never
+ * match either real example. Splitting on any non-letter run and comparing whole tokens sidesteps that.
+ */
+const SUSPECT_NAME_TOKENS = new Set(['skin', 'torso']);
+function globToRegExp(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`);
+}
+function regionIsHideEligibleForSlot(region, slotType) {
+    const globs = bodyRegionHide_1.DEFAULT_HIDE_REGIONS_BY_SLOT_TYPE[slotType] ?? [];
+    return globs.some((glob) => globToRegExp(glob).test(region));
+}
+/** Disjoint-set union over triangle indices. */
+class Dsu {
+    parent;
+    constructor(n) {
+        this.parent = new Int32Array(n);
+        for (let i = 0; i < n; i++)
+            this.parent[i] = i;
+    }
+    find(x) {
+        while (this.parent[x] !== x) {
+            this.parent[x] = this.parent[this.parent[x]];
+            x = this.parent[x];
+        }
+        return x;
+    }
+    union(a, b) {
+        const ra = this.find(a);
+        const rb = this.find(b);
+        if (ra !== rb)
+            this.parent[ra] = rb;
+    }
+}
+/**
+ * Group a primitive's triangles into connected surfaces by SHARED EDGE (both
+ * vertices of a triangle side), not shared vertex — see file header for why
+ * this is the correct granularity: it keeps one authored surface as one
+ * island while never bridging two surfaces that merely happen to touch at a
+ * single decimation-welded point. Exported for reuse by the strip tool.
+ */
+function findTriangleIslands(prim) {
+    const indicesAcc = prim.getIndices();
+    const posAcc = prim.getAttribute('POSITION');
+    if (!indicesAcc || !posAcc)
+        return [];
+    const indices = indicesAcc.getArray();
+    const triangleCount = indices.length / 3;
+    const dsu = new Dsu(triangleCount);
+    const edgeToTriangle = new Map();
+    const edgeKey = (a, b) => (a < b ? `${a}:${b}` : `${b}:${a}`);
+    for (let t = 0; t < triangleCount; t++) {
+        const i = t * 3;
+        const a = indices[i];
+        const b = indices[i + 1];
+        const c = indices[i + 2];
+        for (const [x, y] of [
+            [a, b],
+            [b, c],
+            [c, a],
+        ]) {
+            const key = edgeKey(x, y);
+            const other = edgeToTriangle.get(key);
+            if (other !== undefined)
+                dsu.union(t, other);
+            else
+                edgeToTriangle.set(key, t);
+        }
+    }
+    const byRoot = new Map();
+    for (let t = 0; t < triangleCount; t++) {
+        const root = dsu.find(t);
+        let entry = byRoot.get(root);
+        if (!entry) {
+            entry = { triangleStarts: [], vertices: new Set() };
+            byRoot.set(root, entry);
+        }
+        const i = t * 3;
+        entry.triangleStarts.push(i);
+        entry.vertices.add(indices[i]);
+        entry.vertices.add(indices[i + 1]);
+        entry.vertices.add(indices[i + 2]);
+    }
+    return [...byRoot.values()];
+}
+const textureDecodeCache = new WeakMap();
+async function decodeMaterialBaseColor(material) {
+    const cached = textureDecodeCache.get(material);
+    if (cached)
+        return cached;
+    const promise = (async () => {
+        const texture = material.getBaseColorTexture();
+        if (!texture)
+            return null;
+        const bytes = texture.getImage();
+        if (!bytes)
+            return null;
+        const buffer = Buffer.from(bytes);
+        if ((0, ktx2Decode_1.isKtx2)(buffer)) {
+            const { data, width, height } = await (0, ktx2Decode_1.decodeKtx2ToRgba)(buffer);
+            return { data, width, height };
+        }
+        const out = await (0, sharp_1.default)(buffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+        const { data, info } = out;
+        if (info.channels === 4)
+            return { data, width: info.width, height: info.height };
+        const rgba = Buffer.alloc(info.width * info.height * 4);
+        for (let i = 0; i < info.width * info.height; i++) {
+            for (let c = 0; c < 4; c++)
+                rgba[i * 4 + c] = c < info.channels ? data[i * info.channels + c] : 255;
+        }
+        return { data: rgba, width: info.width, height: info.height };
+    })();
+    textureDecodeCache.set(material, promise);
+    return promise;
+}
+function sampleFlatGray(tex, u, v) {
+    const wu = u - Math.floor(u);
+    const wv = v - Math.floor(v);
+    const x = Math.min(tex.width - 1, Math.max(0, Math.round(wu * (tex.width - 1))));
+    const y = Math.min(tex.height - 1, Math.max(0, Math.round(wv * (tex.height - 1))));
+    const idx = (y * tex.width + x) * 4;
+    const a = tex.data[idx + 3] / 255;
+    if (a <= 0.1)
+        return 'transparent';
+    const r = tex.data[idx] / 255;
+    const g = tex.data[idx + 1] / 255;
+    const b = tex.data[idx + 2] / 255;
+    const maxc = Math.max(r, g, b);
+    const minc = Math.min(r, g, b);
+    const sat = maxc > 0 ? (maxc - minc) / maxc : 0;
+    const val = maxc;
+    // Same thresholds as the original evidence scan's graycheck.py, applied per-sample instead of per-pixel-of-a-render.
+    return sat < 0.08 && val > 0.35 && val < 0.88 ? 'gray' : 'colored';
+}
+/** Dominant HELIX body region among a set of vertex indices, by the SAME dominant-joint classification `bakeBodyRegions.ts` uses. */
+function classifyDominantRegion(prim, jointNames, vertices, dominantRegionShareThreshold) {
+    const jointRegionIndex = jointNames.map((name) => {
+        const region = (0, bakeBodyRegions_1.regionForJoint)(name);
+        return region === null ? bakeBodyRegions_1.UNCLASSIFIED_REGION_INDEX : bodyRegionHide_1.HELIX_BODY_REGIONS.indexOf(region);
+    });
+    const sets = [];
+    for (const s of [0, 1]) {
+        const j = prim.getAttribute(`JOINTS_${s}`);
+        const w = prim.getAttribute(`WEIGHTS_${s}`);
+        if (j && w)
+            sets.push({ j, w });
+    }
+    if (sets.length === 0)
+        return null;
+    const counts = new Map();
+    let classified = 0;
+    const jBuf = [0, 0, 0, 0];
+    const wBuf = [0, 0, 0, 0];
+    for (const vertex of vertices) {
+        let dominantWeight = -1;
+        let dominantJoint = -1;
+        for (const { j, w } of sets) {
+            j.getElement(vertex, jBuf);
+            w.getElement(vertex, wBuf);
+            for (let k = 0; k < 4; k++) {
+                const weight = wBuf[k];
+                if (weight > dominantWeight) {
+                    dominantWeight = weight;
+                    dominantJoint = jBuf[k];
+                }
+            }
+        }
+        const regionIndex = dominantJoint >= 0 ? jointRegionIndex[dominantJoint] : bakeBodyRegions_1.UNCLASSIFIED_REGION_INDEX;
+        if (regionIndex !== bakeBodyRegions_1.UNCLASSIFIED_REGION_INDEX) {
+            classified++;
+            counts.set(regionIndex, (counts.get(regionIndex) ?? 0) + 1);
+        }
+    }
+    if (classified === 0)
+        return null;
+    let bestRegion = -1;
+    let bestCount = 0;
+    for (const [region, count] of counts) {
+        if (count > bestCount) {
+            bestCount = count;
+            bestRegion = region;
+        }
+    }
+    if (bestRegion < 0 || bestCount / classified < dominantRegionShareThreshold)
+        return null;
+    return bodyRegionHide_1.HELIX_BODY_REGIONS[bestRegion];
+}
+/**
+ * Sample this island's own UVs against its material's decoded base-color
+ * texture and report what fraction of samples carry no real authored
+ * content: either flat/gray (the `graycheck.py` heuristic) OR fully
+ * transparent.
+ *
+ * Transparent counts as "untextured" too, and deliberately stays in the
+ * denominator rather than being skipped: geometry nobody meant to ship often
+ * never got a real UV unwrap at all, so its texture coordinates land on empty
+ * atlas padding rather than a packed island — a vertex reading alpha=0 is not
+ * "no signal", it IS the signal.
+ */
+function sampleIslandUntexturedFraction(prim, texture, island, maxSamples) {
+    const uvAcc = prim.getAttribute('TEXCOORD_0');
+    if (!uvAcc)
+        return { untexturedFraction: 0, samplesAttempted: 0 };
+    const indicesAcc = prim.getIndices();
+    const indices = indicesAcc.getArray();
+    const uvBuf = [0, 0];
+    const totalTriangles = island.triangleStarts.length;
+    const stride = Math.max(1, Math.floor(totalTriangles / Math.max(1, Math.floor(maxSamples / 3))));
+    let untextured = 0;
+    let attempted = 0;
+    for (let t = 0; t < totalTriangles; t += stride) {
+        const start = island.triangleStarts[t];
+        for (let k = 0; k < 3; k++) {
+            const vertex = indices[start + k];
+            uvAcc.getElement(vertex, uvBuf);
+            const verdict = sampleFlatGray(texture, uvBuf[0], uvBuf[1]);
+            attempted++;
+            if (verdict === 'gray' || verdict === 'transparent')
+                untextured++;
+        }
+    }
+    return { untexturedFraction: attempted === 0 ? 0 : untextured / attempted, samplesAttempted: attempted };
+}
+/**
+ * Bounded whole-item sample of how much of the mesh's own surface reads as
+ * genuinely AUTHORED texture (`colored`) vs flat grey / transparent — the
+ * item-level gate described in `DetectLeftoverBodyGeometryOptions.itemColoredFractionFloor`.
+ */
+async function sampleItemColoredFraction(document, maxSamples) {
+    let colored = 0;
+    let attempted = 0;
+    for (const node of document.getRoot().listNodes()) {
+        const mesh = node.getMesh();
+        if (!mesh)
+            continue;
+        for (const prim of mesh.listPrimitives()) {
+            const material = prim.getMaterial();
+            const indicesAcc = prim.getIndices();
+            const uvAcc = prim.getAttribute('TEXCOORD_0');
+            if (!material || !indicesAcc || !uvAcc)
+                continue;
+            const texture = await decodeMaterialBaseColor(material);
+            if (!texture)
+                continue;
+            const indices = indicesAcc.getArray();
+            const triangleCount = indices.length / 3;
+            const stride = Math.max(1, Math.floor(triangleCount / Math.max(1, Math.floor(maxSamples / 3))));
+            const uvBuf = [0, 0];
+            for (let t = 0; t < triangleCount; t += stride) {
+                const start = t * 3;
+                for (let k = 0; k < 3; k++) {
+                    uvAcc.getElement(indices[start + k], uvBuf);
+                    const verdict = sampleFlatGray(texture, uvBuf[0], uvBuf[1]);
+                    attempted++;
+                    if (verdict === 'colored')
+                        colored++;
+                }
+            }
+        }
+    }
+    return { coloredFraction: attempted === 0 ? 0 : colored / attempted, samples: attempted };
+}
+/**
+ * Scan every skinned mesh primitive in `document` for triangle islands
+ * (edge-adjacency — see file header) that look like leftover
+ * base-body/underwear geometry. Returns every finding; callers decide
+ * whether to throw (`assertNoLeftoverBodyGeometry`) or just report.
+ */
+async function detectLeftoverBodyGeometry(document, options) {
+    const minTriangles = options.minTriangles ?? DEFAULT_MIN_TRIANGLES;
+    const untexturedFractionThreshold = options.untexturedFractionThreshold ?? DEFAULT_UNTEXTURED_FRACTION_THRESHOLD;
+    const namePatternUntexturedFractionThreshold = options.namePatternUntexturedFractionThreshold ?? DEFAULT_NAME_PATTERN_UNTEXTURED_FRACTION_THRESHOLD;
+    const dominantRegionShareThreshold = options.dominantRegionShareThreshold ?? DEFAULT_DOMINANT_REGION_SHARE_THRESHOLD;
+    const maxSamplesPerIsland = options.maxSamplesPerIsland ?? DEFAULT_MAX_SAMPLES_PER_ISLAND;
+    const minSamplesAttempted = options.minSamplesAttempted ?? DEFAULT_MIN_SAMPLES_ATTEMPTED;
+    const itemColoredFractionFloor = options.itemColoredFractionFloor ?? DEFAULT_ITEM_COLORED_FRACTION_FLOOR;
+    const minTotalFlaggedTriangles = options.minTotalFlaggedTriangles ?? DEFAULT_MIN_TOTAL_FLAGGED_TRIANGLES;
+    // Item-level gate: a garment that has essentially NO authored texture
+    // anywhere is simply a plain/monochrome garment — its untextured surface IS
+    // the garment, not a duplicate of the body. Leftover body geometry only
+    // exists where there is ALSO a real garment surface for it to sit under.
+    const { coloredFraction } = await sampleItemColoredFraction(document, maxSamplesPerIsland);
+    if (coloredFraction < itemColoredFractionFloor)
+        return [];
+    const findings = [];
+    const meshes = document.getRoot().listMeshes();
+    for (const node of document.getRoot().listNodes()) {
+        const mesh = node.getMesh();
+        const skin = node.getSkin();
+        if (!mesh || !skin)
+            continue;
+        const jointNames = skin.listJoints().map((j) => j.getName());
+        const meshIndex = meshes.indexOf(mesh);
+        const prims = mesh.listPrimitives();
+        for (let primIndex = 0; primIndex < prims.length; primIndex++) {
+            const prim = prims[primIndex];
+            const material = prim.getMaterial();
+            const islands = findTriangleIslands(prim);
+            const namedSuspect = matchSuspectName(mesh, node, material);
+            for (let islandIndex = 0; islandIndex < islands.length; islandIndex++) {
+                const island = islands[islandIndex];
+                const triangleCount = island.triangleStarts.length;
+                if (triangleCount < minTriangles)
+                    continue;
+                const dominantRegion = classifyDominantRegion(prim, jointNames, island.vertices, dominantRegionShareThreshold);
+                const texture = material ? await decodeMaterialBaseColor(material) : null;
+                const { untexturedFraction, samplesAttempted } = texture
+                    ? sampleIslandUntexturedFraction(prim, texture, island, maxSamplesPerIsland)
+                    : { untexturedFraction: 0, samplesAttempted: 0 };
+                const enoughSamples = samplesAttempted >= minSamplesAttempted;
+                const regionSignal = enoughSamples &&
+                    dominantRegion !== null &&
+                    regionIsHideEligibleForSlot(dominantRegion, options.slotType) &&
+                    untexturedFraction >= untexturedFractionThreshold;
+                const nameSignal = enoughSamples && namedSuspect !== null && untexturedFraction >= namePatternUntexturedFractionThreshold;
+                if (regionSignal || nameSignal) {
+                    findings.push({
+                        nodeName: node.getName(),
+                        meshIndex,
+                        primIndex,
+                        islandIndex,
+                        triangleCount,
+                        dominantRegion,
+                        untexturedFraction: Math.round(untexturedFraction * 1000) / 1000,
+                        samplesAttempted,
+                        matchedNamePattern: namedSuspect,
+                        reason: regionSignal ? 'region-and-texture' : 'name-pattern',
+                    });
+                }
+            }
+        }
+    }
+    // Total-size floor — see `minTotalFlaggedTriangles` for the measured gap this sits in.
+    const totalFlaggedTriangles = findings.reduce((sum, f) => sum + f.triangleCount, 0);
+    if (totalFlaggedTriangles < minTotalFlaggedTriangles)
+        return [];
+    return findings;
+}
+function matchSuspectName(mesh, node, material) {
+    for (const candidate of [mesh.getName(), node.getName(), material?.getName() ?? '']) {
+        for (const token of candidate.split(/[^a-zA-Z]+/)) {
+            if (SUSPECT_NAME_TOKENS.has(token.toLowerCase()))
+                return token;
+        }
+    }
+    return null;
+}
+/** Human-readable summary for an error message / CLI report — one line per finding. */
+function describeFindings(findings) {
+    return findings
+        .map((f) => `  - node "${f.nodeName}" mesh[${f.meshIndex}] prim[${f.primIndex}] island[${f.islandIndex}]: ` +
+        `${f.triangleCount} tris, region=${f.dominantRegion ?? 'unclassified'}, untexturedFraction=${f.untexturedFraction} (n=${f.samplesAttempted}), ` +
+        `reason=${f.reason}${f.matchedNamePattern ? ` (name matched "${f.matchedNamePattern}")` : ''}`)
+        .join('\n');
+}
+/**
+ * Throws with a full, itemized report if `document` contains anything that
+ * looks like leftover base-body/underwear geometry. This is the gate
+ * `executeCharacterAddon` calls right after `importCharacter` produces the
+ * add-on's final GLB — the add-on is not a valid deliverable until this
+ * passes, exactly like `assertLooksLikeGlb`/`inspectBaseAvatarGlb` gate the
+ * OTHER ways a character artifact can be malformed.
+ */
+async function assertNoLeftoverBodyGeometry(document, options) {
+    const findings = await detectLeftoverBodyGeometry(document, options);
+    if (findings.length === 0)
+        return;
+    throw new Error(`Refusing to package this character add-on (slotType=${options.slotType}): ` +
+        `${findings.length} triangle island(s) look like leftover base-body/underwear geometry baked into the garment mesh — ` +
+        `an add-on's GLB must contain ONLY the garment surface; it renders on top of the platform's own real host body.\n` +
+        `${describeFindings(findings)}\n` +
+        `This is measured to be a TRIP LINE, not an oracle: against the 76 live add-ons it catches both known real ` +
+        `regressions exactly, at a measured residual false-positive rate (see the class doc's "MEASURED PRECISION"). ` +
+        `If you have LOOKED at this item and confirmed the flagged surface is legitimate (a plain/dark garment panel, an ` +
+        `inner lining, a sole bed), re-check the source export for a body/underwear layer left visible for authoring ` +
+        `reference — and if there genuinely is none, pass \`allowFalsePositive: true\` to package it anyway.`);
+}
+/**
+ * Same as `assertNoLeftoverBodyGeometry`, but records and swallows a
+ * confirmed false positive instead of refusing — the escape hatch the bridge
+ * exposes so a creator is never permanently blocked by the trip line.
+ */
+async function assertNoLeftoverBodyGeometryWithOverride(document, options) {
+    if (options.allowFalsePositive)
+        return detectLeftoverBodyGeometry(document, options);
+    await assertNoLeftoverBodyGeometry(document, options);
+    return [];
+}
+//# sourceMappingURL=bodyGeometryGuard.js.map