compat-hunter

name	compat-hunter
description	Use when hunting for OBJ/GLB/glTF/VOX parser compatibility issues by streaming candidate models, parsing each immediately, deleting clean files, and retaining only actionable failures, unknown warnings, or unexplained zero-polygon outputs. Especially useful in the polycss repo with scripts/compat-hunter.mjs.

Compat Hunter

Use this skill when the user wants to keep digging for parser compatibility issues without building a fixed local corpus.

Workflow

1. In the repo, prefer the reusable script:

   pnpm compat-hunter -- --max-models 2000
   

   Equivalent explicit form:

   pnpm --filter @layoutit/polycss-core build
   node .agents/skills/compat-hunter/scripts/compat-hunter.mjs --max-models 2000
   

2. Let the script stream remote OBJ/GLB/glTF/VOX candidates, parse each model, and discard clean files. Reports are written under bench/results/, which is ignored by git.

3. Treat these as known non-actionable unless the user asks to support them:

   • glTF POINTS/LINES/LINE_LOOP/LINE_STRIP primitives.
   • Required Draco or meshopt compressed primitives skipped with a warning.
   • STL source-quality diagnostics that the parser already handles: degenerate triangles, repaired winding, component orientation, non-manifold/shared-edge topology, supplied-normal mismatches, malformed normals/facets, overdeclared binary triangle counts, trailing binary bytes, and ignored non-Magics binary attribute bytes.
   • Empty/corrupt STL containers with no complete triangle records or no valid ASCII facets.

4. Stop and inspect anything classified as:

   • throw
   • unknown-warning
   • obj-zero-no-warning
   • glb-zero-no-warning

5. If an actionable parser issue is found, keep the saved file under the report's interesting/ directory, add a focused parser test using that behavior, implement the smallest fix, and rerun the focused parser tests plus the hunter on the saved file or source class.

Useful Commands

Fresh Objaverse and expanded GitHub stream:

pnpm compat-hunter -- --max-models 5000 --max-bytes 10mb --timeout-ms 30000

Objaverse only, later shards:

pnpm compat-hunter -- --sources objaverse --objaverse-shards 120:220 --max-models 5000

GitHub only:

pnpm compat-hunter -- --sources github --max-models 500

Poly Haven only:

pnpm compat-hunter -- --sources polyhaven --polyhaven-limit 250 --max-models 200

VOX-heavy GitHub sources:

pnpm compat-hunter -- --sources github --github-repos ephtracy/voxel-model@master:vox/,mikelovesrobots/mmmm@master:vox/ --max-models 1000

Local directory:

pnpm compat-hunter -- --sources local --local-root /tmp/models --max-models 1000

Keep known-warning files too:

pnpm compat-hunter -- --keep-known --max-models 500

For STL hunts, --keep-known keeps warning-only models under known/ and the report includes warningCategoriesByKind plus stlDiagnostics on retained rows. Unknown STL warning text, throws, zero-polygon outputs, and suspicious DOM collapses remain interesting/.

Avoid repeating the same shuffled queue:

pnpm compat-hunter -- --sources thingi10k --exts stl --max-models 5000 --seed "$(date +%s)" --queue-offset 5000

Skip models already attempted by prior reports:

pnpm compat-hunter -- --sources thingi10k --exts stl --max-models 5000 --skip-report bench/results/<previous-run>/report.json

Continue after interesting cases:

pnpm compat-hunter -- --no-stop-on-interesting --max-models 2000

Reporting

Summarize the final report.json with:

pnpm compat-hunter -- --report bench/results/<run>/report.json

In the final response, state the attempted/parsed counts, whether any interesting files were retained, and whether the findings are actionable. Do not imply a clean stream proves full compatibility; it only means this pass found no new actionable parser issue.